dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/cli/src/widgets.js

@@ -0,0 +1,208 @@
+// dexterm — pack WIDGETS in the app (task-1358 Tier 5). A pack widget is an html page the popup host serves in a
+// loopback HUD window under a hash-only CSP (r2: no nonce — every inline block is allow-listed by sha256, nothing is
+// substituted into the pack html), fed PUBLIC view models over the host's socket. This adapter is the whole of what a
+// widget can see:
+//   * which widgets exist and are ENABLED (config.plugins['<pack>/<widget>'].enabled — the user's consent from
+//     `dexterm pack widget … --enable`; a pack cannot flip it);
+//   * the page bytes, read from the installed pack directory only after the pack re-hashes to its install record
+//     (a page edited after install is refused), never a symlink, never outside the pack, size-capped, and audited
+//     once more for loaders (<script src>, <link>, frames, <meta http-equiv>, @import, the __NONCE__ token);
+//   * the per-topic view models (rows · token · narrative · positions · alerts · theme) built from what the
+//     terminal already shows. No keys, no signer state, no caps, no mandates, no gate, no pair/source ids.
+// Widgets receive; they cannot ask for anything (the only events a page may send are the generic close/focus/drag).
+import { lstatSync, readFileSync, realpathSync, existsSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { checkIntegrity, packsDir, packWidgetKey, WIDGET_REF } from '../../custom/src/index.js';
+import { WIDGET_HTML_MAX, auditWidgetHtml } from '../../popup/src/index.js';
+import { popupThemeFrom } from "./popup.js";
+const REF = new RegExp(WIDGET_REF);
+/** Every widget of every installed pack, with its consent flag. */
+export function installedWidgets(ui) {
+    return (ui?.packs?.widgets ?? []).map((w) => ({ key: packWidgetKey(w.pack, w.name), pack: w.pack, name: w.name, dir: w.dir, enabled: w.enabled, manifest: w.manifest }));
+}
+/** Split `<pack>/<widget>[/<id>]`; null when malformed. */
+export function parseWidgetRef(ref) {
+    if (!REF.test(ref))
+        return null;
+    const [pack, name, id] = ref.split('/');
+    return { key: `${pack}/${name}`, pack, name, id: id ?? null };
+}
+export function widgetEnabled(ui, ref) {
+    const r = parseWidgetRef(ref);
+    if (!r)
+        return false;
+    return installedWidgets(ui).some((w) => w.key === r.key && w.enabled);
+}
+/**
+ * The page to serve for a widget ref, or a refusal. Consent (enabled), integrity (the installed pack still hashes to
+ * its record), containment (the page is a plain file under the widget directory) and size are all re-checked at
+ * open time, not trusted from startup.
+ */
+export function widgetPage(ui, ref) {
+    const r = parseWidgetRef(ref);
+    if (!r)
+        return { ok: false, reason: `bad widget ref "${ref}" (<pack>/<widget>[/<id>])` };
+    const w = installedWidgets(ui).find((x) => x.key === r.key);
+    if (!w)
+        return { ok: false, reason: `no installed widget ${r.key} (dexterm pack list)` };
+    if (!w.enabled)
+        return { ok: false, reason: `${r.key} is not enabled (dexterm pack widget ${r.pack} ${r.name} --enable)` };
+    const rec = (ui?.config.packs ?? []).find((p) => p.name === r.pack);
+    if (!rec || !ui)
+        return { ok: false, reason: `pack ${r.pack} has no install record` };
+    const packDir = join(packsDir(ui.home), `${rec.name}@${rec.version}`);
+    const integ = checkIntegrity(packDir);
+    if (!integ.ok || integ.hash !== rec.hash)
+        return { ok: false, reason: `pack ${r.pack} changed since install (${integ.ok ? 'hash differs' : integ.reason}); re-install it` };
+    const spec = r.id ? w.manifest.widgets.find((x) => x.id === r.id) : w.manifest.widgets[0];
+    if (!spec)
+        return { ok: false, reason: `${r.key} has no widget "${r.id}" (${w.manifest.widgets.map((x) => x.id).join(', ')})` };
+    const path = resolve(w.dir, spec.page);
+    let root;
+    try {
+        root = realpathSync(w.dir);
+    }
+    catch {
+        return { ok: false, reason: `${r.key}: directory missing` };
+    }
+    if (!existsSync(path) || lstatSync(path).isSymbolicLink())
+        return { ok: false, reason: `${r.key}: page ${spec.page} is missing or a symlink` };
+    const real = realpathSync(path);
+    if (!real.startsWith(root + sep) || !lstatSync(real).isFile())
+        return { ok: false, reason: `${r.key}: page ${spec.page} is outside the widget directory` };
+    const html = readFileSync(real, 'utf8');
+    if (html.length > WIDGET_HTML_MAX)
+        return { ok: false, reason: `${r.key}: page is ${html.length} chars (max ${WIDGET_HTML_MAX})` };
+    // r2: install refused loaders already; a pack installed before that check (or a hash-valid page nobody re-inspected)
+    // is refused here too, with the reason, before the host ever sees it
+    const problems = auditWidgetHtml(html);
+    if (problems.length)
+        return { ok: false, reason: `${r.key}: page ${spec.page} refused: ${problems.join('; ')}` };
+    return { ok: true, page: { key: r.id ? `${r.key}/${r.id}` : `${r.key}/${spec.id}`, title: spec.title, topics: [...spec.topics], html } };
+}
+// ------------------------------------------------------------------ view models (public columns only)
+const FORBIDDEN_KEYS = /^(arm|armed|sign|signer|keys?|caps?|mandates?|gate|secret|token|apiKey|passphrase|seed|privateKey)$/i;
+export function widgetRowsVM(state) {
+    const rows = [];
+    const seen = new Set();
+    for (const r of state.screener.rows) {
+        if (!r.mint || r.skeleton || seen.has(r.mint))
+            continue;
+        seen.add(r.mint);
+        rows.push({
+            symbol: r.symbol, name: r.name, mint: r.mint, launchpad: r.launchpad,
+            price: r.price, mcap: r.mcap, liq: r.liq, vol5m: r.vol5m, vol1h: r.vol1h, vol24: r.vol24,
+            chg: { ...r.chg }, ageMin: r.ageMin, holders: r.holders, org: r.org, top10: r.top10,
+            flags: r.flags.map((f) => String(f)), verified: r.verified,
+        });
+        if (rows.length >= 200)
+            break;
+    }
+    return { feed: state.screener.preset, rows, updatedAt: state.now.getTime() };
+}
+export function widgetPositionsVM(state) {
+    const rows = [];
+    const live = state.live;
+    if (live) {
+        try {
+            for (const p of live.positions.view().rows)
+                rows.push({ symbol: p.symbol, mint: p.mint, side: 'long', tokens: p.tokens, valueSol: p.valueSol, unrealizedSol: p.unrealizedSol, unrealizedPct: p.unrealizedPct, book: 'paper' });
+        }
+        catch { /* no paper book on this run */ }
+        const lp = live.livePositions;
+        if (lp) {
+            try {
+                for (const p of lp.positions()) {
+                    if (p.tokensRaw <= 0n)
+                        continue;
+                    const h = lp.held(p.mint);
+                    rows.push({ symbol: p.symbol, mint: p.mint, side: 'long', tokens: h?.tokens ?? Number(p.tokensRaw) / 10 ** p.decimals, valueSol: null, unrealizedSol: null, unrealizedPct: null, book: 'live' });
+                }
+            }
+            catch { /* ledger unreadable */ }
+        }
+    }
+    return { rows, updatedAt: state.now.getTime() };
+}
+export function widgetAlertsVM(state, limit = 50) {
+    const items = [];
+    const now = state.now.getTime();
+    for (const l of state.rulesUi?.log ?? [])
+        if (l.kind === 'alert' || l.kind === 'proposal')
+            items.push({ at: l.at, level: l.level, kind: `rule:${l.kind}`, text: l.text, symbol: l.symbol || null });
+    const store = state.live?.watch.store;
+    if (store) {
+        try {
+            const symbolOf = (mint) => (mint ? state.screener.rows.find((r) => r.mint === mint)?.symbol ?? null : null);
+            for (const e of store.events(limit))
+                items.push({ at: e.t, level: e.level, kind: e.kind, text: e.text, symbol: symbolOf(e.mint) });
+        }
+        catch { /* store closed */ }
+    }
+    else {
+        for (const a of state.fx.alerts)
+            items.push({ at: now - a.ago * 1000, level: a.level, kind: a.kind, text: a.text, symbol: null });
+    }
+    items.sort((a, b) => b.at - a.at);
+    return { items: items.slice(0, limit), updatedAt: now };
+}
+/** The payload for one topic right now, or null when that topic has nothing yet (token with no coin open, narrative before the board). */
+export function widgetPayload(state, topic, deps = {}) {
+    switch (topic) {
+        case 'rows': return widgetRowsVM(state);
+        case 'token': return deps.token?.() ?? null;
+        case 'narrative': return deps.narrative?.() ?? null;
+        case 'positions': return widgetPositionsVM(state);
+        case 'alerts': return widgetAlertsVM(state);
+        case 'theme': return popupThemeFrom(state.theme);
+        default: return null;
+    }
+}
+/** Defence in depth for tests and the sync path: no money-shaped key anywhere in a payload. */
+export function payloadKeys(v, acc = []) {
+    if (v && typeof v === 'object')
+        for (const [k, x] of Object.entries(v)) {
+            acc.push(k);
+            payloadKeys(x, acc);
+        }
+    return acc;
+}
+export function payloadIsPublic(v) { return !payloadKeys(v).some((k) => FORBIDDEN_KEYS.test(k)); }
+/** Minimum spacing between pushes of the same topic to the same widget (rows refresh every 10 s anyway). */
+export const WIDGET_SYNC_MS = 1000;
+/**
+ * Push fresh view models to every open widget (self-throttled per widget+topic). `force` ignores the throttle
+ * (first paint after `ready`, a theme change). Pure over the controller: a missing controller is a no-op.
+ */
+export function syncWidgetPopups(state, deps = {}, opts = {}) {
+    const p = state.popups;
+    if (!p?.openWidgets || !p.syncWidget)
+        return 0;
+    const open = p.openWidgets();
+    if (!open.length)
+        return 0;
+    const now = state.now.getTime();
+    const stamps = (state.widgetSync ??= new Map());
+    const cache = new Map();
+    let pushed = 0;
+    for (const w of open) {
+        if (opts.only && w.key !== opts.only)
+            continue;
+        for (const topic of w.topics) {
+            if (opts.topics && !opts.topics.includes(topic))
+                continue;
+            const stampKey = `${w.key}|${topic}`;
+            if (!opts.force && now - (stamps.get(stampKey) ?? -Infinity) < WIDGET_SYNC_MS)
+                continue;
+            if (!cache.has(topic))
+                cache.set(topic, widgetPayload(state, topic, deps));
+            const payload = cache.get(topic) ?? null;
+            if (!payload || !payloadIsPublic(payload))
+                continue;
+            p.syncWidget(w.key, topic, payload);
+            stamps.set(stampKey, now);
+            pushed++;
+        }
+    }
+    return pushed;
+}

package/dist/packages/cli/src/workspace-cmd.js

@@ -0,0 +1,68 @@
+// `dexterm workspace <list|show|remove|init> …` (task-1358 Tier 1): the workspace files under
+// ~/.dexterm/workspaces/ (DEXTERM_HOME overrides). No network, no model, never touches a key file.
+//   list            built-ins + files, with errors for files that do not validate
+//   show <name>     print the workspace JSON (a built-in prints its generated form)
+//   remove <name>   delete a user file (built-ins cannot be removed)
+//   init            write `default` as an editable file with the shipped layout trees, if it does not exist
+import { listWorkspaces, readWorkspace, removeWorkspace, writeWorkspace, dextermHome, builtinScreens, defaultWorkspace, workspacesDir } from '../../custom/src/index.js';
+export const WORKSPACE_USAGE = `usage: dexterm workspace list | show <name> | remove <name> | init
+  files: ~/.dexterm/workspaces/<name>.json (DEXTERM_HOME overrides); in the app: ctrl+w then w/n/N/s/m/o/d/1-9, or --workspace <name>`;
+export async function workspaceCommand(argv, io) {
+    const home = dextermHome(io.env);
+    const [cmd, name] = argv;
+    const bad = (s) => { io.stderr.write(`dexterm workspace: ${s}\n${WORKSPACE_USAGE}\n`); return 2; };
+    switch (cmd) {
+        case undefined:
+        case 'list': {
+            const list = listWorkspaces(home);
+            io.stdout.write(`${workspacesDir(home)}\n`);
+            for (const w of list) {
+                const tag = w.builtin ? 'built-in' : 'file';
+                const what = w.error ? `⚠ ${w.error}` : [w.workspace.description, w.workspace.start ? `starts on ${w.workspace.start}` : null, w.workspace.theme ? `theme ${w.workspace.theme}` : null, w.workspace.popups?.length ? `${w.workspace.popups.length} popup(s): ${w.workspace.popups.map((p) => p.kind).join(', ')}` : null].filter(Boolean).join(' · ');
+                io.stdout.write(`  ${w.name.padEnd(24)} ${tag.padEnd(9)} ${what}\n`);
+            }
+            return 0;
+        }
+        case 'show': {
+            if (!name)
+                return bad('show needs a name');
+            const ws = readWorkspace(home, name);
+            if (!ws) {
+                io.stderr.write(`dexterm workspace: no workspace "${name}" (see: dexterm workspace list)\n`);
+                return 1;
+            }
+            io.stdout.write(JSON.stringify(ws, null, 2) + '\n');
+            return 0;
+        }
+        case 'remove': {
+            if (!name)
+                return bad('remove needs a name');
+            const entry = listWorkspaces(home).find((w) => w.name === name);
+            if (!entry) {
+                io.stderr.write(`dexterm workspace: no workspace "${name}"\n`);
+                return 1;
+            }
+            if (entry.builtin) {
+                io.stderr.write(`dexterm workspace: "${name}" is built in; it cannot be removed (save a file with that name to override it)\n`);
+                return 1;
+            }
+            if (!removeWorkspace(home, name)) {
+                io.stderr.write(`dexterm workspace: could not remove ${entry.path}\n`);
+                return 1;
+            }
+            io.stdout.write(`removed ${entry.path}\n`);
+            return 0;
+        }
+        case 'init': {
+            const existing = listWorkspaces(home).find((w) => w.name === 'default' && !w.builtin);
+            if (existing) {
+                io.stdout.write(`${existing.path} already exists\n`);
+                return 0;
+            }
+            const path = writeWorkspace(home, { ...defaultWorkspace(), description: 'The shipped layout as editable pane trees (dexterm workspace init)', screens: builtinScreens() });
+            io.stdout.write(`wrote ${path}\n  edit the trees (weight / fixed / priority / collapseBelow), then ctrl+w d in the app or --workspace default\n`);
+            return 0;
+        }
+        default: return bad(`unknown subcommand "${cmd}"`);
+    }
+}

package/dist/packages/cli/src/x-cmd.js

@@ -0,0 +1,154 @@
+// dexterm — `dexterm x <status|set-client-id|login|logout>` (task-1357, lane I-02). Login with X through
+// OAuth 2.0 PKCE on the fixed loopback callback; each user brings their OWN X app Client ID (their developer
+// account, their rate limits, their bill). Tokens live in ~/.dexterm/x/tokens.json (0600) and are never
+// printed: `status` shows the handle, scopes, ages and file modes only. No `.write`/`dm.*` scope is ever
+// requested; dexterm never posts.
+import { XOAuth, XTokenStore, XAuthError, XApi, XSource, XSpendMeter, KolStore, X_SCOPES, callbackUri, redactXSecrets } from '../../data/src/index.js';
+export const X_HELP = `  dexterm x status             Login with X: client id stored? logged in as @handle? scopes, expiry, file modes
+  dexterm x set-client-id      store YOUR X app's Client ID (prompted on the terminal, or one line on stdin with --stdin)
+  dexterm x login              OAuth2 PKCE in your browser → tokens in ~/.dexterm/x/tokens.json (0600); read scopes only
+  dexterm x logout             revoke both tokens at X and delete the local record`;
+const fmtIn = (ms) => {
+    if (ms <= 0)
+        return 'expired';
+    const m = Math.round(ms / 60_000);
+    return m < 60 ? `${m} min` : `${Math.round(m / 6) / 10} h`;
+};
+/** Read one line from stdin (piped) or the TTY. Never echoes it back. */
+function readLine(io, prompt) {
+    const stdin = io.stdin;
+    if (!stdin)
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        let buf = '';
+        let done = false;
+        const finish = (v) => { if (done)
+            return; done = true; try {
+            stdin.off?.('data', onData);
+        }
+        catch { /* ignore */ } try {
+            stdin.pause?.();
+        }
+        catch { /* ignore */ } resolve(v); };
+        const onData = (chunk) => { buf += chunk.toString(); const nl = buf.indexOf('\n'); if (nl >= 0)
+            finish(buf.slice(0, nl).trim()); };
+        if (stdin.isTTY)
+            io.stderr.write(prompt);
+        stdin.setEncoding?.('utf8');
+        stdin.on('data', onData);
+        stdin.once?.('end', () => finish(buf.trim() || null));
+        stdin.resume?.();
+    });
+}
+function printStatus(io, store, now) {
+    const meta = store.meta();
+    const modes = store.modes();
+    const clientId = store.clientId(io.env);
+    const oct = (m) => (m === null ? '—' : m.toString(8).padStart(3, '0'));
+    io.stdout.write(`client id: ${clientId ? `stored (${io.env.DEXTERM_X_CLIENT_ID ? 'DEXTERM_X_CLIENT_ID' : store.clientIdPath})` : 'missing — run `dexterm x set-client-id` (create a Native App with callback ' + callbackUri() + ' in your X developer portal)'}\n`);
+    if (!meta.loggedIn) {
+        io.stdout.write(`login: not logged in — run \`dexterm x login\`${clientId ? '' : ' after storing the client id'}\n`);
+    }
+    else {
+        io.stdout.write(`login: ${meta.user ? `@${meta.user.username} (id ${meta.user.id})` : 'logged in (handle unknown)'} · scopes ${meta.scopes.join(' ') || '—'} · access token ${meta.expiresAt !== null ? (meta.expiresAt > now ? `valid ${fmtIn(meta.expiresAt - now)}` : 'expired (refreshes on next use)') : '?'} · refresh ${meta.hasRefresh ? 'yes' : 'no (login again)'}\n`);
+    }
+    io.stdout.write(`files: ${store.dir} (mode ${oct(modes.dir)}) · tokens.json ${modes.tokens === null ? 'absent' : `mode ${oct(modes.tokens)}`} · client-id ${modes.clientId === null ? 'absent' : `mode ${oct(modes.clientId)}`}\n`);
+    if ((modes.tokens !== null && modes.tokens !== 0o600) || (modes.dir !== null && modes.dir !== 0o700))
+        io.stderr.write('⚠ permissions are looser than 0600/0700; dexterm will tighten them on the next write (or chmod them now)\n');
+    io.stdout.write(`callback: ${callbackUri()} · tokens are never printed, logged, or sent to a model · X reads are user-context only (your rate limits, your bill)\n`);
+}
+/** Run the `x` subcommand. Returns a process exit code. */
+export async function runX(argv, io, over = {}) {
+    const sub = argv[0] ?? 'status';
+    const store = over.store ?? new XTokenStore({ env: io.env });
+    const now = over.now ?? (() => Date.now());
+    if (sub === 'status') {
+        printStatus(io, store, now());
+        return 0;
+    }
+    if (sub === 'set-client-id') {
+        const useStdin = argv.includes('--stdin');
+        if (!useStdin && !(io.stdin && io.stdin.isTTY)) {
+            io.stderr.write('dexterm x set-client-id: paste the id on a terminal, or pipe ONE line with --stdin (never put it on the command line)\n');
+            return 2;
+        }
+        const v = await readLine(io, 'paste your X app Client ID and press enter: ');
+        if (!v) {
+            io.stderr.write('dexterm x set-client-id: nothing read\n');
+            return 2;
+        }
+        try {
+            store.setClientId(v);
+        }
+        catch (e) {
+            io.stderr.write(`dexterm x set-client-id: ${e instanceof Error ? e.message : String(e)}\n`);
+            return 2;
+        }
+        io.stdout.write(`stored (${v.length} chars) at ${store.clientIdPath} (mode 600). Next: dexterm x login\n`);
+        return 0;
+    }
+    if (sub === 'login') {
+        const oauth = new XOAuth({ store, endpoints: over.endpoints, open: over.open, port: over.port, loginTimeoutMs: over.loginTimeoutMs, now: over.now });
+        if (!store.clientId(io.env)) {
+            io.stderr.write(`dexterm x login: no client id stored. Create a Native App (OAuth 2.0, callback ${callbackUri(over.port)}) in your X developer portal, then run \`dexterm x set-client-id\`.\n`);
+            return 2;
+        }
+        io.stdout.write(`Opening your browser to X (scopes: ${X_SCOPES.join(' ')} — read only; dexterm never posts). Callback ${callbackUri(over.port)}.\n`);
+        const t = setTimeout(() => { if (oauth.lastAuthorizeUrl)
+            io.stderr.write(`If the browser did not open, paste this URL into it:\n${oauth.lastAuthorizeUrl}\n`); }, 4000);
+        t.unref?.();
+        try {
+            const res = await oauth.login({ env: io.env });
+            clearTimeout(t);
+            io.stdout.write(`✓ logged in${res.user ? ` as @${res.user.username}` : ''} · scopes ${res.scopes.join(' ')} · access token valid ${fmtIn(res.expiresAt - now())} · refresh ${res.hasRefresh ? 'yes' : 'no'} · browser ${Math.round(res.callbackMs / 100) / 10}s · exchange ${res.exchangeMs}ms\n`);
+            io.stdout.write(`tokens: ${store.tokensPath} (mode 600). The SOCIAL panel and TRENDING board now read X with your own limits.\n`);
+            return 0;
+        }
+        catch (e) {
+            clearTimeout(t);
+            const msg = e instanceof Error ? e.message : String(e);
+            io.stderr.write(`dexterm x login failed: ${redactXSecrets(msg)}\n`);
+            if (e instanceof XAuthError && e.kind === 'exchange' && /invalid_client/.test(msg))
+                io.stderr.write('  the Client ID is not one X recognises — check the app in your developer portal and re-run `dexterm x set-client-id`\n');
+            if (e instanceof XAuthError && e.kind === 'port-busy')
+                io.stderr.write(`  port ${over.port ?? 41287} is in use; close the other login (or the process on that port) and retry\n`);
+            return 1;
+        }
+    }
+    if (sub === 'logout') {
+        const oauth = new XOAuth({ store, endpoints: over.endpoints, open: over.open, port: over.port, now: over.now });
+        const out = await oauth.logout(io.env);
+        if (!out.hadTokens) {
+            io.stdout.write('not logged in; nothing to revoke.\n');
+            return 0;
+        }
+        const parts = Object.entries(out.revoked).map(([k, s]) => `${k.replace('_token', '')} ${s === 200 ? 'revoked' : s === 0 ? 'unreachable' : `HTTP ${s}`}`);
+        io.stdout.write(`✓ logged out · ${parts.join(' · ') || 'nothing to revoke'} · local tokens deleted. You can also check x.com/settings/connected_apps.\n`);
+        return 0;
+    }
+    io.stderr.write(`dexterm x: unknown subcommand ${JSON.stringify(sub)} (expected status | set-client-id | login | logout)\n`);
+    return 2;
+}
+/**
+ * `dexterm kol import-x` (task-1357): the user's OWN X lists → `own-x-list` KOL lists (handles only). Needs a
+ * login; a degraded X (401/429/403/budget) is reported as text, never as an empty import.
+ */
+export async function importOwnXLists(opts) {
+    const store = opts.store ?? new XTokenStore({ env: opts.env });
+    if (!store.meta().loggedIn)
+        return { ok: false, error: 'not logged in to X — run `dexterm x login` first (your own X app, read scopes only)' };
+    const oauth = new XOAuth({ store, endpoints: opts.endpoints, now: opts.now });
+    const api = new XApi({ oauth, endpoints: opts.endpoints, cache: opts.cache, spend: new XSpendMeter({ cache: opts.cache, env: opts.env, now: opts.now }), env: opts.env });
+    const kol = new KolStore({ cache: opts.cache });
+    const x = new XSource({ api, store, kol, now: opts.now });
+    try {
+        const r = await x.importOwnLists();
+        return { ok: true, lists: r.lists };
+    }
+    catch (e) {
+        return { ok: false, error: redactXSecrets(e instanceof Error ? e.message : String(e)) };
+    }
+    finally {
+        x.close();
+    }
+}

package/dist/packages/custom/src/config.js

@@ -0,0 +1,213 @@
+// @dexterm/custom — the config loader (task-1358 Tier 1). ~/.dexterm/config.json is the canonical,
+// machine-written config (0600, `version: 4`); workspaces are one JSON file each in ~/.dexterm/workspaces/,
+// user themes in ~/.dexterm/themes/. THIS MODULE NEVER READS A KEY FILE: `<name>.key` files are the data
+// layer's business, and the only thing the loader does with a key is move one OUT of an old config.
+//
+// Failure model: a missing config is the defaults (nothing is written until the user saves something); an
+// unreadable or invalid config keeps the defaults and reports the error so the app can show a toast and
+// `dexterm doctor` can name the file. Nothing here throws on I/O except `saveConfig` / `writeWorkspace`.
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, renameSync, unlinkSync, statSync, appendFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { CONFIG_VERSION, defaultConfig, migrate, validateConfig } from "./schema.js";
+import { applyOps } from "./schema.js";
+import { builtinWorkspaces, parseWorkspace, validateWorkspace } from "./workspace.js";
+/** `DEXTERM_HOME` overrides `~/.dexterm` (tests point it at a temp dir). Same rule as the CLI's boot-state. */
+export function dextermHome(env = process.env) {
+    return env.DEXTERM_HOME && env.DEXTERM_HOME.trim() ? env.DEXTERM_HOME : join(homedir(), '.dexterm');
+}
+export const configPath = (home) => join(home, 'config.json');
+export const journalPath = (home) => join(home, 'config.journal.jsonl');
+export const workspacesDir = (home) => join(home, 'workspaces');
+export const packsDir = (home) => join(home, 'packs');
+const sha = (s) => createHash('sha256').update(s).digest('hex');
+/** Load (and migrate if needed) ~/.dexterm/config.json. Never throws. */
+export function loadConfig(home) {
+    const path = configPath(home);
+    const base = { config: defaultConfig(), path, missing: false, ok: true, errors: [], notes: [], extractedKeyFiles: [], hash: sha('') };
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { ...base, missing: true };
+        return { ...base, ok: false, errors: [`${path}: ${e.message}`] };
+    }
+    base.hash = sha(text);
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        return { ...base, ok: false, errors: [`${path}: not valid JSON (${e.message}); keeping defaults`] };
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return { ...base, ok: false, errors: [`${path}: expected an object; keeping defaults`] };
+    const version = Number(raw.version ?? 1);
+    if (version === CONFIG_VERSION) {
+        const errors = validateConfig(raw);
+        if (errors.length)
+            return { ...base, ok: false, errors: errors.slice(0, 5).map((e) => `${path}: ${e.path || '/'} ${e.msg}`) };
+        return { ...base, config: raw };
+    }
+    // older (or newer) config: migrate, back up, write the new one, write extracted keys to <name>.key (0600)
+    let m;
+    try {
+        m = migrate(raw);
+    }
+    catch (e) {
+        return { ...base, ok: false, errors: [`${path}: ${e.message}`] };
+    }
+    if (m.errors.length)
+        return { ...base, ok: false, errors: m.errors.slice(0, 5).map((e) => `${path}: after migration ${e.path || '/'} ${e.msg}`) };
+    const out = { ...base, config: m.config, notes: [...m.notes] };
+    try {
+        writeFileSync(`${path}.bak-v${m.from}`, text, { mode: 0o600 });
+        for (const [name, value] of Object.entries(m.extractedKeys)) {
+            const kf = join(home, `${name}.key`);
+            if (!existsSync(kf)) {
+                writeFileSync(kf, value + '\n', { mode: 0o600 });
+                out.extractedKeyFiles.push(`${name}.key`);
+            }
+            else
+                out.notes.push(`${name}.key already exists; the key in config.json was dropped, not copied`);
+        }
+        saveConfig(home, m.config);
+        out.notes.push(`migrated config.json v${m.from} → v${CONFIG_VERSION} (backup: config.json.bak-v${m.from})`);
+        out.hash = sha(readFileSync(path, 'utf8'));
+    }
+    catch (e) {
+        out.ok = false;
+        out.errors.push(`${path}: migration could not be written (${e.message}); using the migrated config for this run only`);
+    }
+    return out;
+}
+/** Validate + write config.json atomically (0600, directory 0700). Throws on a schema error or I/O failure. */
+export function saveConfig(home, config) {
+    const errors = validateConfig(config);
+    if (errors.length)
+        throw new Error(`config invalid: ${errors[0].path || '/'} ${errors[0].msg}`);
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    const path = configPath(home);
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, path);
+}
+export function readJournal(home) {
+    try {
+        return readFileSync(journalPath(home), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}
+/** Apply ops to the stored config, journal them with the inverse, and save. Throws (and writes nothing) on a bad op or schema error. */
+export function applyAndJournal(home, ops, meta) {
+    const loaded = loadConfig(home);
+    if (!loaded.ok)
+        throw new Error(loaded.errors[0]);
+    const { doc, inverse } = applyOps(loaded.config, ops);
+    const errors = validateConfig(doc);
+    if (errors.length)
+        throw new Error(`refused: ${errors[0].path || '/'} ${errors[0].msg}`);
+    saveConfig(home, doc);
+    const after = sha(readFileSync(configPath(home), 'utf8'));
+    const seq = (readJournal(home).at(-1)?.seq ?? 0) + 1;
+    const entry = { seq, at: meta.now ?? Date.now(), kind: meta.kind ?? 'apply', actor: meta.actor, why: meta.why, ops, inverse, hashBefore: loaded.hash, hashAfter: after };
+    appendFileSync(journalPath(home), JSON.stringify(entry) + '\n', { mode: 0o600 });
+    return { config: doc, entry };
+}
+/** Undo the last applied/redone change if the config has not been edited by hand since. */
+export function undoLast(home, now = Date.now()) {
+    const j = readJournal(home);
+    // the last entry that can be undone: walk back skipping already-undone applies
+    let depth = 0;
+    for (let i = j.length - 1; i >= 0; i--) {
+        const e = j[i];
+        if (e.kind === 'undo') {
+            depth++;
+            continue;
+        }
+        if (depth > 0) {
+            depth--;
+            continue;
+        }
+        const current = loadConfig(home);
+        if (current.hash !== e.hashAfter)
+            return { ok: false, reason: 'cannot undo: config.json changed since (edited by hand?)' };
+        try {
+            const { entry } = applyAndJournal(home, e.inverse, { actor: 'user', why: `undo #${e.seq}`, kind: 'undo', now });
+            return { ok: true, entry };
+        }
+        catch (err) {
+            return { ok: false, reason: `cannot undo: ${err.message}` };
+        }
+    }
+    return { ok: false, reason: 'nothing to undo' };
+}
+// ------------------------------------------------------------------ workspaces on disk
+export const WS_FILE = /^[a-z][a-z0-9-]{0,39}\.json$/;
+/** Built-ins first (default, morning-hud), then the user's files; a user file with a built-in's name REPLACES it. Bad files are listed with their error. */
+export function listWorkspaces(home) {
+    const out = builtinWorkspaces().map((w) => ({ name: w.name, path: null, workspace: w, builtin: true }));
+    const dir = workspacesDir(home);
+    let files = [];
+    try {
+        files = readdirSync(dir).filter((f) => WS_FILE.test(f)).sort();
+    }
+    catch {
+        return out;
+    }
+    for (const f of files) {
+        const path = join(dir, f);
+        const name = f.slice(0, -5);
+        try {
+            if (statSync(path).isSymbolicLink())
+                continue;
+            const ws = parseWorkspace(readFileSync(path, 'utf8'), f);
+            if (ws.name !== name)
+                throw new Error(`${f}: "name" must be "${name}" (the file name)`);
+            const i = out.findIndex((w) => w.name === name);
+            const entry = { name, path, workspace: ws, builtin: false };
+            if (i >= 0)
+                out[i] = entry;
+            else
+                out.push(entry);
+        }
+        catch (e) {
+            out.push({ name, path, workspace: { name }, builtin: false, error: e.message });
+        }
+    }
+    return out;
+}
+export function readWorkspace(home, name) {
+    return listWorkspaces(home).find((w) => w.name === name && !w.error)?.workspace ?? null;
+}
+/** Write a workspace file (validated, 0600). Throws on a bad document or name. */
+export function writeWorkspace(home, ws) {
+    const errors = validateWorkspace(ws);
+    if (errors.length)
+        throw new Error(`workspace invalid: ${errors[0].path || '/'} ${errors[0].msg}`);
+    if (ws.name.includes('/'))
+        throw new Error('a user workspace name cannot contain "/" (reserved for packs)');
+    mkdirSync(workspacesDir(home), { recursive: true, mode: 0o700 });
+    const path = join(workspacesDir(home), `${ws.name}.json`);
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(ws, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, path);
+    return path;
+}
+export function removeWorkspace(home, name) {
+    if (!/^[a-z][a-z0-9-]{0,39}$/.test(name))
+        return false;
+    const path = join(workspacesDir(home), `${name}.json`);
+    try {
+        unlinkSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/packages/custom/src/index.js

@@ -0,0 +1,10 @@
+// @dexterm/custom — public surface (task-1358).
+export * from "./schema.js";
+export * from "./layout.js";
+export * from "./workspace.js";
+export * from "./config.js";
+export * from "./themes.js";
+export * from "./keymap.js";
+export * from "./rules.js";
+export * from "./packs.js";
+export * from "./widget-html.js";