Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Legacy Export — a portable, self-contained identity bundle.
*
* Gathers identity across every PortOS domain (digital twin, autobiography,
* brain, memories, goals, health) into a zip of Markdown + machine-readable
* JSON + a SHA-256 `manifest.json`. The bundle is readable with **zero PortOS
* running** — plain Markdown/JSON, no database. Closes the GOALS "Knowledge
* Legacy" gap (issue #901).
*
* Modeled after `backup.js`: gather data (each source degrades to a fallback so
* one missing domain never fails the export), build per-section Markdown + JSON,
* compute a SHA-256 manifest, emit `legacy-export:*` socket events, and return a
* single zip Buffer via the dependency-free `zipWriter.js`.
*
* Phase 1 (this file): server-side zip bundle, no PDF, no client UI. PDF
* rendering and the export UI are tracked as follow-up issues.
*/
import { createHash } from 'crypto';
import { hostname } from 'os';
import { PDFDocument, rgb, StandardFonts } from '@cantoo/pdf-lib';
import { createZip } from '../lib/zipWriter.js';
import { getCurrentVersion } from './updateChecker.js';
import { exportDigitalTwin } from './digital-twin-export.js';
import { getStories } from './autobiography.js';
import { getGenomeSummary } from './genome.js';
import { getTasteProfile } from './taste-questionnaire.js';
import { getChronotype, getLongevity } from './identity.js';
import { getTraits } from './digital-twin-analysis.js';
import { getAll as getBrainAll } from './brainStorage.js';
import { getMemories } from './memory.js';
import { getGoalsTree } from './identity/goals.js';
import { getLatestMetricValues } from './appleHealthQuery.js';
const MACHINE_HOST = hostname().toLowerCase().replace(/[^\w.\-]/g, '_') || 'unknown';
// Brain entity stores that belong in a personal legacy bundle. We deliberately
// skip operational stores (`admin`, `buckets`, `inbox`) — they're workflow
// scaffolding, not identity.
const BRAIN_LEGACY_TYPES = ['people', 'projects', 'ideas', 'journals', 'links'];
// Health metrics surfaced in the summary, with the human label used in Markdown.
// Each value carries its own freshness date (last sync) as the source caveat.
// Keys are the canonical stored metric names — `heart_rate_variability_sdnn`
// (the alias in appleHealthQuery resolves it to `heart_rate_variability` too).
// Only metrics whose points expose a numeric `qty`/`Avg`/`value` are listed:
// `getLatestMetricValues` can't extract sleep (stored as `totalSleep`), so sleep
// is left to the dedicated health follow-up rather than perpetually reported absent.
const HEALTH_METRICS = [
['resting_heart_rate', 'Resting heart rate', 'bpm'],
['heart_rate_variability_sdnn', 'Heart rate variability', 'ms'],
['weight_body_mass', 'Body mass', ''],
['step_count', 'Daily steps', ''],
['vo2_max', 'VO₂ max', ''],
];
// Soft size guardrail (issue #901 open Q3). The bundle is intentionally a FULL
// plaintext dump — silently truncating identity data would defeat its purpose —
// so instead of capping, the preview surfaces a warning above this threshold so
// the user knows a large export is coming (and which section drives it). The
// estimate is of the uncompressed content; the delivered zip is deflated and
// smaller. 25 MB is generous for text identity data; a bundle past it is almost
// always a very large brain/memory corpus the user should be aware of.
const SIZE_WARNING_BYTES = 25 * 1024 * 1024;
const HEALTH_CAVEAT =
'> ⚠️ **Source caveat:** the figures below are device-reported (Apple Health / manual lab entry) ' +
'and unvalidated. They are a personal-tracking snapshot, **not a verified medical record**, and ' +
'each line states its own source and freshness.';
/**
* Mask obvious secrets that may have been pasted into free-text identity
* content (brain notes, journals, autobiography). Defense-in-depth: the bundle
* leaves the machine, so a stray API key in a note must not ride along. Pure,
* conservative — only high-confidence token shapes are touched so prose is never
* mangled.
*/
export function redactSecrets(text) {
if (typeof text !== 'string' || !text) return text;
return text
// OpenAI / Anthropic style: sk-..., sk-ant-...
.replace(/\bsk-(?:ant-)?[A-Za-z0-9_-]{20,}\b/g, '[REDACTED]')
// GitHub tokens: ghp_, gho_, ghu_, ghs_, ghr_, github_pat_
.replace(/\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})\b/g, '[REDACTED]')
// AWS access key id
.replace(/\bAKIA[0-9A-Z]{16}\b/g, '[REDACTED]')
// Slack tokens
.replace(/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, '[REDACTED]')
// Bearer tokens in headers
.replace(/\bBearer\s+[A-Za-z0-9._-]{20,}\b/g, 'Bearer [REDACTED]')
// PEM private-key blocks
.replace(/-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/g, '[REDACTED PRIVATE KEY]')
// Quoted config/JSON secret assignments — `"password": "..."`, `api_key='...'`.
// Require the value to be QUOTE-DELIMITED so free-text prose like
// `my secret: I never learned to swim` is not mangled (a real false-positive
// risk in autobiography/journal content). Token-shaped secrets pasted into
// prose are already caught by the specific patterns above, quoted or not.
.replace(/(["']?(?:password|passwd|secret|api[_-]?key|token)["']?\s*[:=]\s*)(["'])[^"'\n]{6,}\2/gi, '$1$2[REDACTED]$2');
}
const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
/**
* Gather identity data across every domain. Each source is independently
* `.catch`-guarded so a single unavailable backend (e.g. Postgres-backed brain
* when running file-only) degrades to an empty section instead of failing the
* whole export.
*/
export async function gatherLegacyData() {
const brainEntries = {};
await Promise.all(BRAIN_LEGACY_TYPES.map(async (type) => {
brainEntries[type] = await getBrainAll(type).catch(() => []);
}));
const [
twinPrompt, claudeMd, stories, genome, taste, chronotype, longevity, traits,
memoriesResult, goalsTree, healthValues,
] = await Promise.all([
exportDigitalTwin('system_prompt').then(r => r?.content || '').catch(() => ''),
exportDigitalTwin('claude_md').then(r => r?.content || '').catch(() => ''),
getStories().catch(() => []),
getGenomeSummary().catch(() => ({ uploaded: false })),
getTasteProfile().catch(() => ({ sections: [] })),
getChronotype().catch(() => null),
getLongevity().catch(() => null),
getTraits().catch(() => null),
getMemories({ limit: 100000 }).catch(() => ({ total: 0, memories: [] })),
getGoalsTree().catch(() => ({ roots: [], flat: [] })),
getLatestMetricValues(HEALTH_METRICS.map(m => m[0])).catch(() => ({})),
]);
return {
twinPrompt,
claudeMd,
stories: Array.isArray(stories) ? stories : [],
genome: genome || { uploaded: false },
taste: taste || { sections: [] },
chronotype: chronotype || null,
longevity: longevity || null,
traits: traits || null,
brain: brainEntries,
memories: Array.isArray(memoriesResult?.memories) ? memoriesResult.memories : [],
goals: Array.isArray(goalsTree?.flat) ? goalsTree.flat : [],
health: healthValues || {},
};
}
// === Section descriptors ===
// Each section is self-describing: how to detect presence, count records, and
// render Markdown + machine-readable JSON. The route's section-filter and the
// manifest both iterate this one list, so adding a domain is a single entry.
const SECTIONS = [
{
key: 'identity',
dir: 'identity',
label: 'Identity & Values',
present: (d) => !!(d.twinPrompt || d.claudeMd || d.traits || d.chronotype || d.longevity || d.taste?.sections?.length),
counts: (d) => ({ hasTwinPrompt: !!d.twinPrompt, traits: d.traits?.dimensions ? Object.keys(d.traits.dimensions).length : 0 }),
files: (d) => {
const out = [];
if (d.twinPrompt) out.push({ name: 'identity/digital-twin-prompt.md', data: redactSecrets(d.twinPrompt) });
if (d.claudeMd) out.push({ name: 'identity/claude.md', data: redactSecrets(d.claudeMd) });
out.push({ name: 'identity/profile.md', data: buildIdentityProfileMd(d) });
out.push({ name: 'data/identity.json', data: jsonFile({
traits: d.traits || null,
chronotype: d.chronotype || null,
longevity: d.longevity || null,
taste: d.taste || null,
genome: d.genome || null,
}) });
return out;
},
},
{
key: 'autobiography',
dir: 'autobiography',
label: 'Life Stories',
present: (d) => d.stories.length > 0,
counts: (d) => ({ stories: d.stories.length }),
files: (d) => [
{ name: 'autobiography/autobiography.md', data: buildAutobiographyMd(d.stories) },
{ name: 'data/autobiography.json', data: jsonFile(d.stories) },
],
},
{
key: 'brain',
dir: 'brain',
label: 'Brain & Memories',
present: (d) => d.memories.length > 0 || BRAIN_LEGACY_TYPES.some(t => (d.brain[t] || []).length > 0),
counts: (d) => ({
memories: d.memories.length,
...Object.fromEntries(BRAIN_LEGACY_TYPES.map(t => [t, (d.brain[t] || []).length])),
}),
files: (d) => {
const out = [];
for (const type of BRAIN_LEGACY_TYPES) {
const records = d.brain[type] || [];
if (records.length === 0) continue;
out.push({ name: `brain/${type}.md`, data: buildBrainTypeMd(type, records) });
}
if (d.memories.length > 0) {
out.push({ name: 'brain/memories.md', data: buildMemoriesMd(d.memories) });
}
out.push({ name: 'data/brain.json', data: jsonFile({ ...d.brain, memories: d.memories }) });
return out;
},
},
{
key: 'goals',
dir: 'goals',
label: 'Goals & Milestones',
present: (d) => d.goals.length > 0,
counts: (d) => ({ goals: d.goals.length }),
files: (d) => [
{ name: 'goals/goals.md', data: buildGoalsMd(d.goals) },
{ name: 'data/goals.json', data: jsonFile(d.goals) },
],
},
{
key: 'decisions',
dir: 'decisions',
label: 'Key Decisions',
// Derived (never a first-class entity) from three existing signals:
// completed goals, completed goal milestones, and decision-tagged brain
// entries. PortOS has no dedicated life-decisions store (decisionLog.js is
// CoS task scheduling), and an ADR records why we keep deriving rather than
// add one (docs/decisions/2026-06-19-legacy-export-decisions-source.md).
present: (d) => collectDecisions(d).length > 0,
counts: (d) => ({ decisions: collectDecisions(d).length }),
files: (d) => [
{ name: 'decisions/key-decisions.md', data: buildDecisionsMd(d) },
],
source: 'Derived from completed goals, completed goal milestones, and decision-tagged brain entries (PortOS has no dedicated life-decisions store; see ADR 2026-06-19-legacy-export-decisions-source).',
},
{
key: 'health',
dir: 'health',
label: 'Health Summary',
present: (d) => HEALTH_METRICS.some(([metric]) => d.health[metric]),
counts: (d) => ({ metrics: HEALTH_METRICS.filter(([m]) => d.health[m]).length }),
files: (d) => [
{ name: 'health/health-summary.md', data: buildHealthMd(d.health) },
{ name: 'data/health.json', data: jsonFile(d.health) },
],
source: 'Device-reported (Apple Health) and manual lab entry — unvalidated, not a medical record.',
},
];
export function getSectionKeys() {
return SECTIONS.map(s => s.key);
}
// === Markdown builders (pure) ===
function mdHeader(title, subtitle) {
return `# ${title}\n\n*${subtitle}*\n`;
}
function buildIdentityProfileMd(d) {
const out = [mdHeader('Identity Profile', 'Personality, chronotype, taste, genome, and longevity')];
if (d.traits?.dimensions) {
out.push('## Personality Traits\n');
const lines = Object.entries(d.traits.dimensions)
.filter(([, v]) => v?.score != null)
.map(([k, v]) => `- **${titleize(k)}**: ${v.score}/100${v.label ? ` (${v.label})` : ''}`);
if (lines.length) out.push(lines.join('\n'));
if (d.traits.summary) out.push(`\n${redactSecrets(d.traits.summary)}`);
}
if (d.chronotype?.type) {
out.push('## Chronotype\n');
out.push(`**Type**: ${d.chronotype.type}${d.chronotype.confidence ? ` (${Math.round(d.chronotype.confidence * 100)}% confidence)` : ''}`);
}
const completed = (d.taste?.sections || []).filter(s => s.status === 'complete');
if (completed.length) {
out.push('## Taste Profile\n');
for (const s of completed) {
out.push(`### ${s.label}\n`);
if (s.summary) out.push(redactSecrets(s.summary));
}
}
if (d.genome?.uploaded) {
out.push('## Genome\n');
const g = [`- **SNPs analyzed**: ${num(d.genome.snpCount) != null ? d.genome.snpCount.toLocaleString() : 'unknown'}`];
if (d.genome.markerCount) g.push(`- **Markers tracked**: ${d.genome.markerCount}`);
out.push(g.join('\n'));
}
if (d.longevity?.estimatedLifeExpectancy) {
out.push('## Longevity\n');
out.push(`- **Estimated life expectancy**: ${d.longevity.estimatedLifeExpectancy} years`);
}
return out.join('\n\n');
}
function buildAutobiographyMd(stories) {
const out = [mdHeader('Autobiography', `${stories.length} life ${stories.length === 1 ? 'story' : 'stories'}`)];
const sorted = [...stories].sort((a, b) =>
(a.themeId || '').localeCompare(b.themeId || '') ||
String(a.createdAt || '').localeCompare(String(b.createdAt || '')));
let theme = null;
for (const story of sorted) {
if (story.themeId !== theme) {
theme = story.themeId;
out.push(`## ${theme ? titleize(theme) : 'Miscellaneous'}\n`);
}
if (story.prompt) out.push(`> *${redactSecrets(story.prompt)}*\n`);
if (story.content) out.push(redactSecrets(story.content));
}
return out.join('\n\n');
}
function buildBrainTypeMd(type, records) {
const out = [mdHeader(titleize(type), `${records.length} ${records.length === 1 ? 'entry' : 'entries'} from the Brain`)];
for (const r of records) {
const title = r.title || r.name || r.label || r.id;
out.push(`## ${redactSecrets(String(title))}`);
const body = r.content || r.body || r.text || r.notes || r.description || '';
if (body) out.push(redactSecrets(String(body)));
if (Array.isArray(r.tags) && r.tags.length) out.push(`*Tags: ${r.tags.join(', ')}*`);
}
return out.join('\n\n');
}
function buildMemoriesMd(memories) {
const out = [mdHeader('Memories', `${memories.length} ${memories.length === 1 ? 'memory' : 'memories'}`)];
const byCategory = {};
for (const m of memories) {
const cat = m.category || 'uncategorized';
(byCategory[cat] ||= []).push(m);
}
for (const [cat, items] of Object.entries(byCategory)) {
out.push(`## ${titleize(cat)}\n`);
for (const m of items) {
const text = m.summary || m.content || '';
if (text) out.push(`- ${redactSecrets(String(text))}`);
}
}
return out.join('\n\n');
}
function buildGoalsMd(goals) {
const out = [mdHeader('Goals & Milestones', `${goals.length} ${goals.length === 1 ? 'goal' : 'goals'}`)];
const active = goals.filter(g => g.status !== 'abandoned');
for (const g of active) {
const status = g.status === 'completed' ? ' [completed]' : num(g.progress) != null ? ` (${g.progress}%)` : '';
out.push(`## ${redactSecrets(String(g.title || 'Untitled'))}${status}`);
if (g.description) out.push(redactSecrets(String(g.description)));
const ms = Array.isArray(g.milestones) ? g.milestones : [];
if (ms.length) {
out.push(ms.map(m => `- [${m.completedAt ? 'x' : ' '}] ${redactSecrets(String(m.title || m.description || ''))}`).join('\n'));
}
}
return out.join('\n\n');
}
// Tokens that mark a brain entry (idea / journal / project) as a deliberate
// life decision — matched case-insensitively against tags and the title.
const DECISION_TOKENS = ['decision', 'decided', 'choice', 'chose', 'pivot'];
function isDecisionEntry(record) {
const tags = Array.isArray(record?.tags) ? record.tags : [];
if (tags.some(t => DECISION_TOKENS.includes(String(t).toLowerCase()))) return true;
const title = String(record?.title || record?.name || record?.label || '').toLowerCase();
return DECISION_TOKENS.some(tok => title.includes(tok));
}
// Gather the decision signals into a single, dated, deduped list. Each item is
// `{ label, detail, date }`. Derivation, not a stored entity — see the ADR.
function collectDecisions(d) {
const out = [];
const goals = Array.isArray(d?.goals) ? d.goals : [];
for (const g of goals) {
if (g.status === 'completed') {
out.push({ label: g.title || 'Goal', detail: g.description || '', date: g.completedAt || g.updatedAt || '' });
}
for (const m of (Array.isArray(g.milestones) ? g.milestones : [])) {
if (m.completedAt) {
out.push({ label: g.title || 'Goal', detail: m.title || m.description || '', date: m.completedAt });
}
}
}
const brain = d?.brain || {};
for (const type of ['ideas', 'journals', 'projects']) {
for (const r of (Array.isArray(brain[type]) ? brain[type] : [])) {
if (!isDecisionEntry(r)) continue;
out.push({
label: r.title || r.name || r.label || 'Note',
detail: r.content || r.body || r.text || r.notes || r.description || '',
date: r.updatedAt || r.createdAt || '',
});
}
}
// Dedup on label+detail (the same milestone could be reachable twice), then
// sort newest-first with undated items last.
const seen = new Set();
const deduped = out.filter(item => {
const key = `${item.label} ${item.detail}`;
if (seen.has(key)) return false;
seen.add(key);
return true;
});
deduped.sort((a, b) => String(b.date || '').localeCompare(String(a.date || '')));
return deduped;
}
function buildDecisionsMd(d) {
const decisions = collectDecisions(d);
const out = [mdHeader('Key Decisions', 'Derived from completed goals, milestones, and decision-tagged notes')];
out.push('> *Source note:* PortOS has no dedicated life-decisions store, so this section is **derived** — from goals carried to completion, completed milestones across goals, and Brain entries you tagged or titled as a decision. Tag a note `decision` to surface it here.');
for (const item of decisions) {
const when = item.date ? ` _(${String(item.date).slice(0, 10)})_` : '';
// The decisions section is a digest — truncate a long brain-entry body to a
// single-line summary (the full text already lives in the Brain section).
// Redact BEFORE truncating: clipping first could cut a token-shaped secret
// below redactSecrets' min-length and leak a partial key (e.g. `ghp_0123…`).
const detail = item.detail ? ` — ${truncateOneLine(redactSecrets(String(item.detail)), 280)}` : '';
out.push(`- **${redactSecrets(String(item.label || 'Decision'))}**${detail}${when}`);
}
return out.join('\n\n');
}
function buildHealthMd(health) {
const out = [mdHeader('Health Summary', 'Self-tracked vitals'), HEALTH_CAVEAT];
const lines = [];
for (const [metric, label, unit] of HEALTH_METRICS) {
const v = health[metric];
if (!v) continue;
const value = v.value != null ? v.value : v;
const date = v.date ? ` (last sync ${String(v.date).slice(0, 10)})` : '';
lines.push(`- **${label}**: ${value}${unit ? ` ${unit}` : ''} — Apple Health${date}`);
}
out.push(lines.length ? lines.join('\n') : '_No health metrics available._');
return out.join('\n\n');
}
// Collapse whitespace/newlines and clip to `max` chars with an ellipsis — used
// to keep the derived decisions digest to one line per item. Pure.
function truncateOneLine(text, max) {
const flat = String(text || '').replace(/\s+/g, ' ').trim();
return flat.length > max ? `${flat.slice(0, max - 1).trimEnd()}…` : flat;
}
function titleize(s) {
return String(s || '')
.replace(/([A-Z])/g, ' $1')
.replace(/[_-]+/g, ' ')
.replace(/\s+/g, ' ')
.trim()
.replace(/^./, c => c.toUpperCase());
}
// Serialize to JSON with the SAME secret redaction the Markdown renderers
// apply — the `data/*.json` mirror is the half of the bundle most likely to be
// machine-scraped, so a token pasted into a note must not ride along in it
// either. The replacer touches every string value.
function jsonFile(obj) {
return JSON.stringify(obj, (_key, value) => (typeof value === 'string' ? redactSecrets(value) : value), 2);
}
// === Bundle assembly ===
const README_PRIVACY_BANNER =
'# PortOS Legacy Export\n\n' +
'> ⚠️ **Privacy notice:** this bundle contains your full plaintext identity — autobiography, ' +
'brain notes, memories, goals, and health/genome summaries. It was generated on your machine, ' +
'at your request, and is **not** uploaded anywhere by PortOS. Treat the file as sensitive: anyone ' +
'who opens it can read everything inside.\n\n' +
'This is a self-contained portrait of your identity, knowledge, and life story — readable with no ' +
'PortOS running. Open any `.md` file for the human-readable record; the `data/` folder mirrors each ' +
'section as machine-readable JSON, and `manifest.json` indexes every file with a SHA-256 checksum.\n';
function sha256(buf) {
return createHash('sha256').update(buf).digest('hex');
}
/**
* Build the list of bundle files for the selected sections. Pure over gathered
* `data` — no I/O. Returns `{ files, sections }` where `files` is the
* `{ name, data }` list ready for `createZip` and `sections` is the manifest's
* per-section presence/counts metadata.
*/
export function buildBundleFiles(data, { sections: selected = null } = {}) {
const wanted = Array.isArray(selected) && selected.length
? SECTIONS.filter(s => selected.includes(s.key))
: SECTIONS;
const files = [];
const sectionMeta = {};
for (const section of SECTIONS) {
const present = section.present(data);
const included = wanted.includes(section);
sectionMeta[section.key] = {
label: section.label,
present,
included: included && present,
...(present ? section.counts(data) : {}),
...(section.source ? { source: section.source } : {}),
};
if (included && present) {
for (const f of section.files(data)) {
files.push({ name: f.name, data: Buffer.isBuffer(f.data) ? f.data : Buffer.from(String(f.data), 'utf-8') });
}
}
}
return { files, sections: sectionMeta };
}
/**
* Build the manifest object (SHA-256 per file). `kind`/`schemaVersion` let a
* future reader (or `parseZip` round-trip verifier) validate the bundle.
*/
export function buildManifest(files, { sections, portosVersion, generatedAt, pdfIncluded = false }) {
const fileHashes = {};
for (const f of files) fileHashes[f.name] = sha256(f.data);
return {
schemaVersion: 1,
kind: 'portos-legacy-export',
generatedAt,
portosVersion,
host: MACHINE_HOST,
sections,
files: fileHashes,
fileCount: files.length,
pdf: { included: !!pdfIncluded, ...(pdfIncluded ? { file: 'legacy-portrait.pdf' } : {}) },
};
}
// === PDF rendering (Phase 2) ===
// A rendered, human-readable portrait of the same per-section Markdown the
// bundle already produces. Uses @cantoo/pdf-lib (already a dependency, shared with
// `pipeline/comicPdf.js`) — Helvetica family, basic word-wrap, heading sizing.
// No images, no external fonts: the Markdown bundle stays the primary artifact;
// the PDF is a convenience for reading/printing offline.
const PDF_PAGE = { width: 612, height: 792 }; // US Letter, in points
const PDF_MARGIN = 56; // ~0.78in
const PDF_LINE_GAP = 4; // extra leading between lines
const PDF_TEXT_WIDTH = PDF_PAGE.width - PDF_MARGIN * 2;
// Heading sizes by Markdown level (`#`=1 … `###`=3); anything deeper uses level 3.
const PDF_HEADING_SIZE = { 1: 22, 2: 16, 3: 13 };
const PDF_BODY_SIZE = 11;
// Strip the inline Markdown emphasis/link syntax @cantoo/pdf-lib can't render so it
// doesn't print literal `**`/`*`/`[text](url)` markers. Pure.
function stripInlineMarkdown(text) {
return String(text)
.replace(/!?\[([^\]]*)\]\(([^)]*)\)/g, '$1') // [label](url) /  → label
.replace(/\*\*([^*]+)\*\*/g, '$1') // **bold**
.replace(/(^|[^*])\*([^*]+)\*/g, '$1$2') // *italic* (leave bare * alone)
.replace(/`([^`]+)`/g, '$1'); // `code`
}
// WinAnsi (@cantoo/pdf-lib's StandardFont encoding) can't encode arbitrary Unicode —
// an unencodable glyph throws at draw time. Map the few non-ASCII characters
// our Markdown builders actually emit (VO₂, ⚠️, smart quotes) to safe ASCII,
// then drop anything still outside the encodable range. Pure.
//
// @cantoo/pdf-lib's WinAnsi encoder also throws on control bytes that ARE ≤ 0xFF —
// the C0 controls (0x00–0x1F), DEL (0x7F), and the undefined C1 range
// (0x80–0x9F) — so a stray control char pasted into free-text identity content
// (brain notes, journals, autobiography) must be stripped BEFORE it reaches
// `widthOfTextAtSize`/`drawText`, or the whole PDF render throws. Tabs become a
// space (lines are already newline-split before they reach here).
function toWinAnsi(text) {
return String(text)
.replace(/[‘’]/g, "'")
.replace(/[“”]/g, '"')
.replace(/[–—]/g, '-')
.replace(/…/g, '...')
.replace(/₂/g, '2') // subscript 2 (VO₂)
.replace(/[•·]/g, '-') // bullet / middot → ASCII dash (U+2022 is > 0xFF, would otherwise be stripped)
.replace(/[✅⚠️⚡]/g, '') // ✅ ⚠ emoji-variation ⚡
.replace(/\t/g, ' ')
// eslint-disable-next-line no-control-regex
.replace(/[\x00-\x1F\x7F-\x9F]/g, '') // control bytes WinAnsi can't encode
// eslint-disable-next-line no-control-regex
.replace(/[^\x00-\xFF]/g, ''); // anything still above the WinAnsi range
}
// Word-wrap a single logical line to fit `maxWidth` at `size`. A single token
// longer than the line (e.g. a long URL) is hard-broken so it never overflows.
// Pure given the font's metrics.
function wrapLine(text, font, size, maxWidth) {
const words = text.split(/\s+/).filter(Boolean);
if (words.length === 0) return [''];
const lines = [];
let current = '';
for (const word of words) {
const candidate = current ? `${current} ${word}` : word;
if (font.widthOfTextAtSize(candidate, size) <= maxWidth) {
current = candidate;
continue;
}
if (current) lines.push(current);
// The word itself overflows — hard-break it character by character.
if (font.widthOfTextAtSize(word, size) > maxWidth) {
let chunk = '';
for (const ch of word) {
if (font.widthOfTextAtSize(chunk + ch, size) > maxWidth && chunk) {
lines.push(chunk);
chunk = ch;
} else {
chunk += ch;
}
}
current = chunk;
} else {
current = word;
}
}
if (current) lines.push(current);
return lines;
}
/**
* Render the per-section Markdown into a single PDF. Pure-ish (async only for
* @cantoo/pdf-lib's font embedding) — takes the same `{ name, data }` content files
* `buildBundleFiles` produces and walks the `.md` ones in bundle order.
* Returns the PDF bytes (Uint8Array). `meta` stamps the title page.
*
* @returns {Promise<{ bytes: Uint8Array, pageCount: number }>}
*/
export async function buildLegacyPdf(contentFiles, { portosVersion = '0.0.0', generatedAt = '' } = {}) {
const pdf = await PDFDocument.create();
pdf.setTitle('PortOS Legacy Export');
pdf.setProducer('PortOS');
pdf.setCreator('PortOS legacy export');
const font = await pdf.embedFont(StandardFonts.Helvetica);
const fontBold = await pdf.embedFont(StandardFonts.HelveticaBold);
let page = pdf.addPage([PDF_PAGE.width, PDF_PAGE.height]);
let cursor = PDF_PAGE.height - PDF_MARGIN;
// Draw one wrapped block; paginates when the cursor runs past the bottom margin.
const draw = (raw, { size = PDF_BODY_SIZE, bold = false, color = rgb(0.12, 0.12, 0.12), gapAfter = PDF_LINE_GAP } = {}) => {
const f = bold ? fontBold : font;
const text = toWinAnsi(stripInlineMarkdown(raw));
for (const line of wrapLine(text, f, size, PDF_TEXT_WIDTH)) {
if (cursor - size < PDF_MARGIN) {
page = pdf.addPage([PDF_PAGE.width, PDF_PAGE.height]);
cursor = PDF_PAGE.height - PDF_MARGIN;
}
page.drawText(line, { x: PDF_MARGIN, y: cursor - size, size, font: f, color });
cursor -= size + gapAfter;
}
};
const space = (h = PDF_BODY_SIZE) => { cursor -= h; };
// Title page.
draw('PortOS Legacy Export', { size: 28, bold: true, color: rgb(0, 0, 0) });
space(6);
draw('A self-contained portrait of identity, knowledge, and life story.', { size: 12, color: rgb(0.35, 0.35, 0.35) });
if (generatedAt) draw(`Generated: ${generatedAt.slice(0, 19).replace('T', ' ')} UTC`, { size: 10, color: rgb(0.45, 0.45, 0.45) });
draw(`PortOS ${portosVersion}`, { size: 10, color: rgb(0.45, 0.45, 0.45) });
const markdownFiles = contentFiles.filter(f => f.name.endsWith('.md'));
for (const file of markdownFiles) {
page = pdf.addPage([PDF_PAGE.width, PDF_PAGE.height]);
cursor = PDF_PAGE.height - PDF_MARGIN;
const lines = file.data.toString('utf-8').split('\n');
for (const rawLine of lines) {
const line = rawLine.replace(/\s+$/, '');
const heading = line.match(/^(#{1,6})\s+(.*)$/);
if (heading) {
const level = Math.min(heading[1].length, 3);
space(6);
draw(heading[2], { size: PDF_HEADING_SIZE[level], bold: true, color: rgb(0, 0, 0), gapAfter: 6 });
continue;
}
if (line.trim() === '') { space(6); continue; }
const quote = line.match(/^>\s?(.*)$/);
if (quote) {
draw(quote[1], { color: rgb(0.4, 0.4, 0.4) });
continue;
}
const bullet = line.match(/^[-*]\s+\[[ xX]\]\s+(.*)$/) || line.match(/^[-*]\s+(.*)$/);
if (bullet) {
draw(`• ${bullet[1]}`);
continue;
}
draw(line);
}
}
const bytes = await pdf.save();
return { bytes, pageCount: pdf.getPageCount() };
}
/**
* Build the full legacy-export zip. Returns `{ buffer, manifest }`.
* `io` (optional) receives `legacy-export:*` progress events.
* `includePdf` adds a rendered `legacy-portrait.pdf` (Phase 2); default false —
* the Markdown bundle is the primary artifact.
*/
export async function buildLegacyZip({ sections = null, io = null, includePdf = false } = {}) {
emit(io, 'legacy-export:started', { sections });
const data = await gatherLegacyData();
emit(io, 'legacy-export:progress', { phase: 'gathered' });
const { files, sections: sectionMeta } = buildBundleFiles(data, { sections });
const portosVersion = await getCurrentVersion().catch(() => '0.0.0');
const generatedAt = new Date().toISOString();
// README first, then content files. The optional rendered PDF is derived from
// those same Markdown files (so it carries no data the bundle doesn't already
// expose) and joins the hashed file set. The manifest hashes every content
// file — build it before adding manifest.json so it doesn't hash itself.
const readme = { name: 'README.md', data: Buffer.from(README_PRIVACY_BANNER, 'utf-8') };
const contentFiles = [readme, ...files];
if (includePdf) {
const { bytes, pageCount } = await buildLegacyPdf(contentFiles, { portosVersion, generatedAt });
contentFiles.push({ name: 'legacy-portrait.pdf', data: Buffer.from(bytes) });
emit(io, 'legacy-export:progress', { phase: 'pdf', pageCount });
}
const manifest = buildManifest(contentFiles, { sections: sectionMeta, portosVersion, generatedAt, pdfIncluded: includePdf });
const manifestFile = { name: 'manifest.json', data: Buffer.from(jsonFile(manifest), 'utf-8') };
// Deflate the bundle (per-entry, kept only where it shrinks the file) — the
// identity bundle is overwhelmingly text, so this is a large win for free and
// directly answers issue #901 open Q5. Manifest hashes are of the original
// (uncompressed) bytes, so they're unchanged by compression.
const buffer = createZip([...contentFiles, manifestFile], { compress: true });
console.log(`📦 Legacy export: ${manifest.fileCount} files${includePdf ? ' (+PDF)' : ''}, ${(buffer.length / 1024).toFixed(1)} KB`);
emit(io, 'legacy-export:completed', { fileCount: manifest.fileCount, bytes: buffer.length });
return { buffer, manifest };
}
/**
* Lightweight preview — section presence + counts + an estimated byte size,
* WITHOUT building the zip. Used by `GET /api/legacy-export/preview`.
*/
export async function previewLegacyExport() {
const data = await gatherLegacyData();
const { files, sections } = buildBundleFiles(data, { sections: null });
const estimatedBytes = files.reduce((sum, f) => sum + f.data.length, 0);
// Soft size guardrail: warn (don't truncate) when the uncompressed estimate is
// large, and point at the biggest section so the user knows what's driving it.
let sizeWarning = null;
if (estimatedBytes > SIZE_WARNING_BYTES) {
const bySection = sectionByteEstimates(files);
const largest = Object.entries(bySection).sort((a, b) => b[1] - a[1])[0];
sizeWarning = {
thresholdBytes: SIZE_WARNING_BYTES,
estimatedBytes,
largestSection: largest ? largest[0] : null,
};
}
return {
sections,
fileCount: files.length + 2 /* README + manifest */,
estimatedBytes,
sizeWarning,
};
}
// Sum content bytes per section so the preview can name what's driving a large
// bundle. A `data/<section>.json` mirror is attributed to its section (not a
// generic "data" bucket); everything else uses its first path segment. Pure.
function sectionByteEstimates(files) {
const out = {};
for (const f of files) {
let section;
const dataMirror = f.name.match(/^data\/([^/]+)\.json$/);
if (dataMirror) section = dataMirror[1];
else section = f.name.includes('/') ? f.name.slice(0, f.name.indexOf('/')) : f.name;
out[section] = (out[section] || 0) + f.data.length;
}
return out;
}
function emit(io, event, payload) {
if (io && typeof io.emit === 'function') io.emit(event, payload);
}