@north-light/crouter 0.3.154

package/dist/core/scope.js

@@ -0,0 +1,255 @@
+import { homedir } from 'node:os';
+import { existsSync, statSync, realpathSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CRTR_DIR_NAME } from '../types.js';
+import { usage } from './errors.js';
+import { loadProfileManifest } from './profiles/manifest.js';
+// Cache of resolved project-scope-root STACKS, keyed by (resolved cwd, profile
+// id). A profile widens the pointer set beyond the bare cwd (see
+// findProjectScopeRoots below), so the cache key must carry both — the same
+// cwd resolves to a different stack under a different (or no) profile.
+// `resetScopeCache()` (called by every profile mutation in
+// src/core/profiles/manifest.ts) clears the whole cache; there is no
+// per-entry invalidation because a profile edit can change which pointer set
+// any cached cwd belongs to.
+const scopeRootsCache = new Map();
+function scopeRootsCacheKey(resolvedStartDir, profileId) {
+    return `${resolvedStartDir}\u0000${profileId ?? ''}`;
+}
+export function builtinViewsRoot() {
+    // Resolved relative to this file: dist/core/scope.js → dist/builtin-views/
+    // (src/ at dev time).
+    const thisFile = fileURLToPath(import.meta.url);
+    const coreDir = dirname(thisFile);
+    const pkgDir = dirname(coreDir); // src/ or dist/
+    return join(pkgDir, 'builtin-views');
+}
+export function builtinMemoryRoot() {
+    // The substrate's shipped built-in documents live in their OWN package dir,
+    // resolved relative to this file: dist/core/scope.js → dist/builtin-memory/
+    // (src/ at dev time). This is a HARD special case (design verdict m2): builtin
+    // memory is the only content the builtin scope carries — the scope has no
+    // scopeRoot (scopeRoot('builtin') is null).
+    const thisFile = fileURLToPath(import.meta.url);
+    const coreDir = dirname(thisFile);
+    const pkgDir = dirname(coreDir); // src/ or dist/
+    return join(pkgDir, 'builtin-memory');
+}
+export function builtinPiPackagesDir() {
+    const thisFile = fileURLToPath(import.meta.url);
+    const coreDir = dirname(thisFile);
+    const pkgDir = dirname(coreDir); // src/ or dist/
+    return join(pkgDir, 'builtin-pi-packages');
+}
+export function builtinPiPackageDir(name) {
+    return join(builtinPiPackagesDir(), name);
+}
+export function userScopeRoot() {
+    return join(homedir(), CRTR_DIR_NAME);
+}
+function realpathOrSelf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+function isProjectScopeDir(candidate, userRoot) {
+    if (!existsSync(candidate))
+        return false;
+    // Compare realpaths, not raw strings: on macOS `$HOME` is commonly under a
+    // symlinked prefix (`/tmp` -> `/private/tmp`) while `process.cwd()` (the
+    // walk's start point, resolved by the OS) is already realpath'd. A raw
+    // string compare then fails to recognize the user root one level up from a
+    // project dir nested under HOME, leaking the user scope in as a bogus
+    // project scope root.
+    if (realpathOrSelf(candidate) === realpathOrSelf(userRoot))
+        return false;
+    try {
+        return statSync(candidate).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function findProjectScopeRoot(startDir = process.cwd()) {
+    return findProjectScopeRoots(startDir)[0] ?? null;
+}
+/** Walk `startDir` upward collecting every ancestor `.crouter/` dir (nearest
+ *  first). The user-global `~/.crouter/` is excluded because it is the separate
+ *  user scope, not a project ancestor.
+ *
+ *  The walk is FENCED at `homedir()`: it must never climb at or above HOME.
+ *  Home's own `.crouter/` is the user scope (already excluded), and nothing at
+ *  or above HOME is a project ancestor. Without this fence, a relocated HOME
+ *  nested under a directory tree that itself contains a `.crouter/` (e.g. a
+ *  mock-VM home under the real host home) would sweep the host's `~/.crouter`
+ *  (and any other above-HOME `.crouter`) in as a bogus project ancestor,
+ *  leaking one machine's user-global memory into a nested-HOME node. Mirrors
+ *  the on-read positional-walk fence (src/core/substrate/on-read.ts). A read
+ *  whose start dir is outside HOME (e.g. a production VM with HOME=/root and no
+ *  ancestor `.crouter`) never reaches home and walks to the filesystem root, as
+ *  before. */
+function collectAncestorScopeRoots(startDir, userRoot) {
+    const roots = [];
+    const home = realpathOrSelf(homedir());
+    let dir = resolve(startDir);
+    while (true) {
+        const candidate = join(dir, CRTR_DIR_NAME);
+        if (isProjectScopeDir(candidate, userRoot))
+            roots.push(candidate);
+        if (realpathOrSelf(dir) === home)
+            return roots;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return roots;
+        dir = parent;
+    }
+}
+/** Every project scope root visible from `startDir`, nearest first — now a
+ *  PROFILE-AWARE pointer walk, not a single-pointer ancestor walk. Pointers are
+ *  `[startDir]` plus, when `profileId` resolves to a manifest, each of its
+ *  `projects` in manifest order; each pointer independently walks upward
+ *  collecting every ancestor `.crouter/` dir, the pointers' contributions
+ *  concatenate in pointer order, and the combined list dedupes to first
+ *  occurrence — so a `.crouter/` shared by two pointers contributes once, at
+ *  whichever pointer reached it first. `profileId` defaults to the process's
+ *  selected profile (`CRTR_PROFILE_ID`); a null/unresolvable profile collapses
+ *  to the single `[startDir]` pointer, reproducing today's behavior exactly.
+ *  Results are cached per (resolved startDir, profileId) — `resetScopeCache()`
+ *  invalidates on any profile mutation that can change project dirs or names. */
+export function findProjectScopeRoots(startDir = process.cwd(), profileId = process.env['CRTR_PROFILE_ID'] || null) {
+    const resolvedStart = resolve(startDir);
+    const key = scopeRootsCacheKey(resolvedStart, profileId);
+    const cached = scopeRootsCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const userRoot = userScopeRoot();
+    const pointers = [resolvedStart];
+    if (profileId !== null && profileId !== '') {
+        try {
+            const { manifest } = loadProfileManifest(profileId);
+            pointers.push(...manifest.projects);
+        }
+        catch {
+            // Missing/deleted/invalid profile: this is a hot path every memory and
+            // launch-config resolve runs through, so fall back to the bare
+            // `[startDir]` pointer rather than throwing.
+        }
+    }
+    const seen = new Set();
+    const roots = [];
+    for (const pointer of pointers) {
+        for (const root of collectAncestorScopeRoots(pointer, userRoot)) {
+            if (seen.has(root))
+                continue;
+            seen.add(root);
+            roots.push(root);
+        }
+    }
+    scopeRootsCache.set(key, roots);
+    return roots;
+}
+export function projectScopeRoot(startDir) {
+    return findProjectScopeRoot(startDir);
+}
+export function projectScopeRoots(startDir, profileId) {
+    return findProjectScopeRoots(startDir, profileId);
+}
+export function scopeRoot(scope) {
+    // The builtin scope has no scope-root dir: its only content is memory
+    // (builtinMemoryRoot) and views (builtinViewsRoot), both hard special cases.
+    if (scope === 'builtin')
+        return null;
+    return scope === 'user' ? userScopeRoot() : projectScopeRoot();
+}
+export function requireScopeRoot(scope) {
+    const root = scopeRoot(scope);
+    if (!root) {
+        throw usage(`no ${scope} scope available — run \`crtr init\` here or use --scope user`);
+    }
+    return root;
+}
+export function ensureProjectScopeRoot(startDir = process.cwd()) {
+    const found = findProjectScopeRoot(startDir);
+    if (found)
+        return found;
+    // Initialize new project scope at startDir. `found` was falsy, which means
+    // the (resolvedStart, profileId) cache key above resolved to an EMPTY stack
+    // (no pointer had an existing `.crouter/` yet) — seed that same cache entry
+    // with the about-to-exist root so a caller that immediately writes under it
+    // (without an intervening disk rescan) sees it without a stale empty-array
+    // cache hit.
+    const resolvedStart = resolve(startDir);
+    const root = join(resolvedStart, CRTR_DIR_NAME);
+    const profileId = process.env['CRTR_PROFILE_ID'] || null;
+    scopeRootsCache.set(scopeRootsCacheKey(resolvedStart, profileId), [root]);
+    return root;
+}
+export function pluginsDir(scope) {
+    const root = scopeRoot(scope);
+    return root ? join(root, 'plugins') : null;
+}
+export function marketplacesDir(scope) {
+    const root = scopeRoot(scope);
+    return root ? join(root, 'marketplaces') : null;
+}
+export function configuredClisDir(scope) {
+    const root = scopeRoot(scope);
+    return root ? configuredClisDirForRoot(root) : null;
+}
+/** The configured-CLIs cache parent dir under an EXACT scope-root dir. Used to
+ *  address per-root caches when multiple project roots are visible; the single
+ *  source of the `configured-clis` path segment. */
+export function configuredClisDirForRoot(scopeRootDir) {
+    return join(scopeRootDir, 'configured-clis');
+}
+/** Where substrate memory documents live per scope. Builtin memory is the
+ *  special case — its own package dir (builtinMemoryRoot), since the builtin
+ *  scope has no scopeRoot — mirroring viewsDir's builtin handling. User and
+ *  project memory live at scopeRoot(scope)/memory. */
+export function scopeMemoryDir(scope) {
+    if (scope === 'builtin')
+        return builtinMemoryRoot();
+    const root = scope === 'user' ? userScopeRoot() : projectScopeRoot();
+    return root ? join(root, 'memory') : null;
+}
+/** Where a plugin's substrate memory documents live: `<plugin.root>/memory`.
+ *  The resolver mounts these under the virtual `<pluginName>/` namespace. */
+export function pluginMemoryDir(plugin) {
+    return join(plugin.root, 'memory');
+}
+/** Where view definition dirs live per scope. Builtin views sit directly under
+ *  builtinViewsRoot() (no `views/` segment — they ARE the builtin views dir),
+ *  matching the loader's `<root>/<name>/core.mjs` resolution. */
+export function viewsDir(scope) {
+    if (scope === 'builtin')
+        return builtinViewsRoot();
+    const root = scope === 'user' ? userScopeRoot() : projectScopeRoot();
+    return root ? join(root, 'views') : null;
+}
+export function resolveScopeArg(scopeArg) {
+    if (scopeArg === undefined)
+        return 'all';
+    const value = scopeArg.toLowerCase();
+    if (value === 'user' || value === 'project' || value === 'builtin' || value === 'all')
+        return value;
+    throw usage(`invalid --scope: ${scopeArg} (expected user|project|builtin|all)`);
+}
+export function listScopes(scopeArg) {
+    const v = resolveScopeArg(scopeArg);
+    if (v === 'all') {
+        const out = [];
+        if (projectScopeRoot())
+            out.push('project');
+        out.push('user');
+        out.push('builtin');
+        return out;
+    }
+    return [v];
+}
+export function resetScopeCache() {
+    scopeRootsCache.clear();
+}

package/dist/core/secrets.d.ts

@@ -0,0 +1,25 @@
+import type { Scope } from '../types.js';
+/** The 0600 secrets store: raw relay/bearer tokens for `remoteCanvas.targets`,
+ *  kept OUT of `config.json` (which is not permission-hardened and is treated
+ *  as shareable/inspectable) and never logged. `crtr canvas config add
+ *  --relay-token -` is the ONLY accepted form — reads the raw token from
+ *  stdin; any other value is rejected with a generic error (never echoing
+ *  what was received). Keyed by `RemoteCanvasTarget.relayTokenRef`, never by
+ *  the target name directly, so a rename doesn't orphan the secret. */
+export interface SecretsStore {
+    relayTokens: Record<string, string>;
+}
+export declare function readSecrets(scope: Scope): SecretsStore;
+/** Writes secrets.json directly (never via `fs-utils.writeJson`, which has no
+ *  mode control) so the file is created 0600 from the first byte, then
+ *  `chmodSync`s belt-and-suspenders in case the file pre-existed with looser
+ *  permissions (e.g. hand-copied from another machine). */
+export declare function writeSecrets(scope: Scope, store: SecretsStore): void;
+export declare function getRelayToken(ref: string, scope: Scope): string | undefined;
+export declare function setRelayToken(ref: string, token: string, scope: Scope): void;
+export declare function deleteRelayToken(ref: string, scope: Scope): void;
+/** A short, non-reversible display fingerprint of a raw token — safe to print
+ *  in `canvas config list`/`show` output. NEVER derive this from anything
+ *  that could round-trip back to the token, and never log/return the raw
+ *  token itself alongside it. */
+export declare function fingerprint(token: string): string;

package/dist/core/secrets.js

@@ -0,0 +1,55 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { scopeRoot, requireScopeRoot } from './scope.js';
+import { ensureDir } from './fs-utils.js';
+const SECRETS_FILE = 'secrets.json';
+function secretsPathFor(root) {
+    return join(root, SECRETS_FILE);
+}
+export function readSecrets(scope) {
+    const root = scopeRoot(scope);
+    if (!root)
+        return { relayTokens: {} };
+    const p = secretsPathFor(root);
+    if (!existsSync(p))
+        return { relayTokens: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(p, 'utf8'));
+        return { relayTokens: parsed.relayTokens ?? {} };
+    }
+    catch {
+        return { relayTokens: {} };
+    }
+}
+/** Writes secrets.json directly (never via `fs-utils.writeJson`, which has no
+ *  mode control) so the file is created 0600 from the first byte, then
+ *  `chmodSync`s belt-and-suspenders in case the file pre-existed with looser
+ *  permissions (e.g. hand-copied from another machine). */
+export function writeSecrets(scope, store) {
+    const root = requireScopeRoot(scope);
+    ensureDir(root);
+    const p = secretsPathFor(root);
+    writeFileSync(p, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 });
+    chmodSync(p, 0o600);
+}
+export function getRelayToken(ref, scope) {
+    return readSecrets(scope).relayTokens[ref];
+}
+export function setRelayToken(ref, token, scope) {
+    const s = readSecrets(scope);
+    s.relayTokens[ref] = token;
+    writeSecrets(scope, s);
+}
+export function deleteRelayToken(ref, scope) {
+    const s = readSecrets(scope);
+    delete s.relayTokens[ref];
+    writeSecrets(scope, s);
+}
+/** A short, non-reversible display fingerprint of a raw token — safe to print
+ *  in `canvas config list`/`show` output. NEVER derive this from anything
+ *  that could round-trip back to the token, and never log/return the raw
+ *  token itself alongside it. */
+export function fingerprint(token) {
+    return createHash('sha256').update(token).digest('hex').slice(0, 12);
+}

package/dist/core/self-update.d.ts

@@ -0,0 +1,21 @@
+export declare function currentVersion(): string;
+export declare function selfUpdate(): void;
+/** Check whether a newer crtr version is available on npm.
+ *  Warns to stderr if network unavailable; returns {current, latest} or null if unreachable. */
+export declare function selfCheck(): {
+    current: string;
+    latest: string;
+} | null;
+/** Pull updates for all installed marketplaces and standalone plugins. */
+export declare function contentUpdate(): void;
+export interface ContentUpdateEntry {
+    name: string;
+    kind: 'marketplace' | 'plugin';
+    current: string | null;
+    latest: string | null;
+    up_to_date: boolean;
+    unreachable: boolean;
+}
+/** Check whether any marketplace/plugin has updates available.
+ *  Returns per-item status without applying anything. */
+export declare function contentCheck(): ContentUpdateEntry[];

package/dist/core/self-update.js

@@ -0,0 +1,105 @@
+// Self-update and content-check primitives extracted from commands/update.ts.
+// Moved here to break the core→commands import inversion: auto-update.ts
+// (core) previously imported from commands/update.ts (commands layer).
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { join, dirname } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { listAllPlugins, listAllMarketplaces } from './resolver.js';
+import { pull, fetch, currentSha, remoteSha } from './git.js';
+import { updateState } from './config.js';
+import { nowIso } from './fs-utils.js';
+import { general, network } from './errors.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// src/core/self-update.ts → up to src/ → up to pkg root
+const PKG_ROOT = join(__dirname, '..', '..');
+const PACKAGE_JSON_PATH = join(PKG_ROOT, 'package.json');
+export function currentVersion() {
+    const raw = readFileSync(PACKAGE_JSON_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed.version;
+}
+export function selfUpdate() {
+    const res = spawnSync('npm', ['i', '-g', '@north-light/crouter@latest'], { stdio: 'inherit' });
+    if (res.status !== 0) {
+        throw general('npm install failed');
+    }
+}
+/** Check whether a newer crtr version is available on npm.
+ *  Warns to stderr if network unavailable; returns {current, latest} or null if unreachable. */
+export function selfCheck() {
+    const res = spawnSync('npm', ['view', '@north-light/crouter', 'version'], { encoding: 'utf8' });
+    if (res.status !== 0) {
+        return null;
+    }
+    const latest = res.stdout.trim();
+    const current = currentVersion();
+    return { current, latest };
+}
+/** Pull updates for all installed marketplaces and standalone plugins. */
+export function contentUpdate() {
+    const marketplaces = listAllMarketplaces();
+    for (const mkt of marketplaces) {
+        const res = pull(mkt.root);
+        if (res.status !== 0) {
+            throw network(`git pull failed for marketplace ${mkt.name}: ${res.stderr.trim()}`);
+        }
+        updateState(mkt.scope, (s) => {
+            if (!s.marketplaces[mkt.name])
+                s.marketplaces[mkt.name] = {};
+            s.marketplaces[mkt.name].last_updated = nowIso();
+        });
+    }
+    const plugins = listAllPlugins();
+    for (const plugin of plugins) {
+        if (!plugin.enabled)
+            continue;
+        if (plugin.sourceMarketplace)
+            continue;
+        const res = pull(plugin.root);
+        if (res.status !== 0) {
+            throw network(`git pull failed for plugin ${plugin.name}: ${res.stderr.trim()}`);
+        }
+        updateState(plugin.scope, (s) => {
+            if (!s.plugins[plugin.name])
+                s.plugins[plugin.name] = {};
+            s.plugins[plugin.name].last_updated = nowIso();
+        });
+    }
+}
+/** Check whether any marketplace/plugin has updates available.
+ *  Returns per-item status without applying anything. */
+export function contentCheck() {
+    const results = [];
+    const marketplaces = listAllMarketplaces();
+    for (const mkt of marketplaces) {
+        const fetchRes = fetch(mkt.root, mkt.ref);
+        if (fetchRes.status !== 0) {
+            results.push({ name: mkt.name, kind: 'marketplace', current: null, latest: null, up_to_date: true, unreachable: true });
+            continue;
+        }
+        const head = currentSha(mkt.root);
+        const remote = remoteSha(mkt.root, mkt.ref);
+        const up_to_date = head !== null && remote !== null ? head === remote : true;
+        results.push({ name: mkt.name, kind: 'marketplace', current: head, latest: remote, up_to_date, unreachable: false });
+    }
+    const plugins = listAllPlugins();
+    for (const plugin of plugins) {
+        if (!plugin.enabled)
+            continue;
+        if (plugin.sourceMarketplace)
+            continue;
+        const ref = 'main';
+        const fetchRes = fetch(plugin.root, ref);
+        if (fetchRes.status !== 0) {
+            results.push({ name: plugin.name, kind: 'plugin', current: null, latest: null, up_to_date: true, unreachable: true });
+            continue;
+        }
+        const head = currentSha(plugin.root);
+        const remote = remoteSha(plugin.root, ref);
+        const up_to_date = head !== null && remote !== null ? head === remote : true;
+        results.push({ name: plugin.name, kind: 'plugin', current: head, latest: remote, up_to_date, unreachable: false });
+    }
+    return results;
+}

package/dist/core/session-model/session-state.d.ts

@@ -0,0 +1,51 @@
+import type { BrokerToClient, ClientRole, RpcExtensionUIRequest, RpcSessionState, WelcomeFrame } from '../runtime/broker-protocol.js';
+/** A retained `ctx.ui.setWidget` entry. */
+export interface DisplayWidget {
+    lines: string[];
+    placement: 'aboveEditor' | 'belowEditor';
+}
+/** The broker-owned display levels (`ctx.ui.setStatus/setWidget/setTitle`),
+ *  insertion-ordered per key exactly as the broker retains them. */
+export interface DisplayState {
+    statuses: Record<string, string>;
+    widgets: Record<string, DisplayWidget>;
+    title: string | undefined;
+}
+export interface SessionState {
+    /** This viewer's fixed role, stated by the broker in `welcome`. `controller`
+     *  means writable and `observer` means read-only; the broker never reassigns
+     *  it, so nothing after `welcome` can change this field. */
+    role: ClientRole;
+    /** The broker process's pi agent dir, from `welcome` — lets a viewer point an
+     *  AuthStorage/ModelRegistry at the SAME auth.json. */
+    agentDir: string | undefined;
+    /** pi's own `get_state` payload. `undefined` until the first welcome. */
+    engine: RpcSessionState | undefined;
+    /** Live context occupancy in prompt tokens: seeded from the snapshot's
+     *  contextUsage, then tracked off each assistant `message_end`. */
+    contextTokens: number | undefined;
+    /** Queued steering + follow-up message TEXT, from `queue_update`. A fresh
+     *  broker with an empty queue emits no `queue_update`, so every welcome resets
+     *  this rather than leaving a dead broker's rows on screen. */
+    queued: string[];
+    display: DisplayState;
+    /** The blocking dialog awaiting an answer, or null. Only a writable client is
+     *  ever sent one, and every writable client is sent the SAME one — the first
+     *  answer wins and the broker dismisses the rest by id.
+     *  `welcome.pending_dialog` carries one in flight at attach time, and
+     *  a welcome is a COMPLETE catch-up, so a welcome naming none clears it.
+     *  (The terminal viewer does not read this field: its overlay is owned by
+     *  `InputController`, which holds a live TUI handle rather than data. The field
+     *  is still session state — it is derived solely from broker frames — and the
+     *  web SPA renders straight off it.) */
+    dialog: RpcExtensionUIRequest | null;
+}
+export declare function initialSessionState(role?: ClientRole): SessionState;
+/** The whole session state a `welcome` determines, in ONE step. This is why D1
+ *  had to land first: before the broker carried its retained display levels in
+ *  `snapshot.display`, catch-up was `welcome` plus N replayed edges and this
+ *  function could not be total. */
+export declare function applySnapshot(frame: WelcomeFrame): SessionState;
+/** Fold one broker frame into the session state. Pure and total: a frame that
+ *  carries no session state returns `state` UNCHANGED (same reference). */
+export declare function reduce(state: SessionState, frame: BrokerToClient): SessionState;