@north-light/api 0.3.579 → 0.3.587

package/dist/core/runtime/nerd-font.js

@@ -0,0 +1,162 @@
+import { spawnSync } from 'node:child_process';
+import { readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** crtr's viewer renders tool calls, command icons, node badges and the
+ *  inspector with Nerd Font private-use-area codepoints (see
+ *  `core/preview-registry.ts` and `clients/attach/render/tool-calls.ts`), so a
+ *  terminal without a Nerd Font shows tofu boxes for every icon. Nothing about
+ *  the font is auto-detectable from inside the process — the terminal emulator
+ *  picks the face — so the best we can do is detect an INSTALLED Nerd Font on
+ *  the system and tell the user to point their terminal profile at it. */
+/** Font-family and filename fragments that only appear in Nerd Font builds.
+ *  `symbols` alone would false-positive on system symbol faces, so the
+ *  symbols-only patch is matched with its full distributed name. */
+const NERD_FONT_PATTERN = /nerd[ _-]?font|symbolsnerdfont|symbols-only/i;
+/** Font directories searched when fontconfig is unavailable (always the case
+ *  on macOS). User-level dirs first: an install crtr suggested lands there. */
+function fontDirs(platform, home) {
+    if (platform === 'darwin') {
+        return [join(home, 'Library', 'Fonts'), '/Library/Fonts', '/System/Library/Fonts'];
+    }
+    return [
+        join(home, '.local', 'share', 'fonts'),
+        join(home, '.fonts'),
+        '/usr/local/share/fonts',
+        '/usr/share/fonts',
+    ];
+}
+/** Shallow recursive filename scan. Font trees nest a couple of levels
+ *  (`/usr/share/fonts/truetype/<family>/`), so depth 3 reaches every real
+ *  install without walking an unbounded tree. */
+function scanForNerdFont(dir, depth) {
+    if (depth < 0)
+        return null;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return null; // absent or unreadable directory is simply not a match
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            const nested = scanForNerdFont(join(dir, entry.name), depth - 1);
+            if (nested !== null)
+                return nested;
+            continue;
+        }
+        if (!/\.(ttf|otf|ttc)$/i.test(entry.name))
+            continue;
+        if (NERD_FONT_PATTERN.test(entry.name))
+            return entry.name;
+    }
+    return null;
+}
+/** Ask fontconfig for installed families. Present on Linux, absent on macOS. */
+function queryFontconfig() {
+    const probe = spawnSync('sh', ['-lc', 'command -v fc-list >/dev/null 2>&1'], { stdio: 'ignore' });
+    if (probe.status !== 0)
+        return null;
+    const res = spawnSync('fc-list', [':', 'family'], { encoding: 'utf8', timeout: 5000 });
+    if (res.status !== 0 || typeof res.stdout !== 'string')
+        return null;
+    for (const line of res.stdout.split('\n')) {
+        if (NERD_FONT_PATTERN.test(line))
+            return line.split(',')[0].trim();
+    }
+    return ''; // fontconfig answered and knows of no Nerd Font — authoritative miss
+}
+export function detectNerdFont(platform = process.platform, home = homedir()) {
+    if (platform !== 'darwin') {
+        const family = queryFontconfig();
+        if (family !== null && family !== '')
+            return { installed: true, evidence: family, source: 'fc-list' };
+    }
+    for (const dir of fontDirs(platform, home)) {
+        const file = scanForNerdFont(dir, 3);
+        if (file !== null)
+            return { installed: true, evidence: file, source: 'font-dir' };
+    }
+    return { installed: false, evidence: null, source: null };
+}
+/** Download the upstream symbols-only patch into the user's font dir. Works on
+ *  every Linux regardless of package manager — Debian/Ubuntu and Fedora ship no
+ *  Nerd Font package, so there is nothing native to install there. Needs no
+ *  sudo: it writes to `~/.local/share/fonts`.
+ *
+ *  curl runs with its progress meter on (no `-s`) because this is the one
+ *  install step with a real download percentage: setup captures that stderr
+ *  and drives the step's progress bar from it (`parseCurlPercent`). */
+export const NERD_FONT_MANUAL_LINUX_COMMAND = 'mkdir -p ~/.local/share/fonts && '
+    + 'curl -fL -o /tmp/NerdFontsSymbolsOnly.zip '
+    + 'https://github.com/ryanoasis/nerd-fonts/releases/latest/download/NerdFontsSymbolsOnly.zip && '
+    + 'unzip -oq /tmp/NerdFontsSymbolsOnly.zip -d ~/.local/share/fonts && fc-cache -f';
+/** Reads percent complete out of curl's default progress meter as its stderr
+ *  arrives. Rows are separated by `\r` and look like
+ *  `100  1234k  100  1234k    0     0   987k      0 --:--:-- …`; the leading
+ *  column is the percentage of the whole transfer, and the header rows
+ *  (`  % Total    % Received …`) start with `%` so they never match.
+ *
+ *  Stateful because curl's writes split rows anywhere: the tail of a chunk is
+ *  held back until its row is terminated. Reading a half-row instead lands on
+ *  a different column and reports a number that was never true — in practice
+ *  the completed download's own summary row parsed as 0%.
+ *
+ *  Returns the percentage of the last complete row in this chunk, or null when
+ *  the chunk completed no row. */
+export function createCurlPercentReader() {
+    let pending = '';
+    return (chunk) => {
+        pending += chunk;
+        const rows = pending.split(/[\r\n]/);
+        pending = rows.pop() ?? '';
+        let percent = null;
+        for (const row of rows) {
+            const match = /^\s*(\d{1,3})\s+\S+\s+\d{1,3}\s/.exec(row);
+            if (match === null)
+                continue;
+            const value = Number(match[1]);
+            if (value <= 100)
+                percent = value;
+        }
+        return percent;
+    };
+}
+/** The install command for this platform/package manager. `packageManager`
+ *  matches setup's detection: only brew and pacman have a real Nerd Font
+ *  package, everything else on Linux gets the upstream download. A non-brew
+ *  package manager only ever exists on Linux, so it settles the platform on its
+ *  own and `platform` decides only the `manual` case. */
+export function nerdFontInstallCommand(packageManager, platform = process.platform) {
+    const onLinux = platform !== 'darwin' || packageManager === 'apt-get' || packageManager === 'dnf' || packageManager === 'pacman';
+    if (packageManager === 'brew') {
+        return {
+            command: 'brew install --cask font-symbols-only-nerd-font',
+            hint: 'Homebrew cask',
+            autoInstall: true,
+        };
+    }
+    if (packageManager === 'pacman') {
+        return {
+            command: 'sudo pacman -S --noconfirm ttf-nerd-fonts-symbols',
+            hint: 'pacman install',
+            autoInstall: true,
+        };
+    }
+    if (onLinux) {
+        return {
+            command: NERD_FONT_MANUAL_LINUX_COMMAND,
+            hint: 'download symbols-only patch to ~/.local/share/fonts (needs curl + unzip)',
+            autoInstall: true,
+        };
+    }
+    return {
+        command: null,
+        hint: 'install Homebrew, or download a Nerd Font from https://nerdfonts.com and add it in Font Book',
+        autoInstall: false,
+    };
+}
+/** Every install path ends the same way: the font is on disk but the terminal
+ *  emulator still has to be pointed at it, and crtr cannot do that. */
+export const NERD_FONT_SELECT_HINT = 'then set your terminal profile\'s font to a Nerd Font (e.g. add "Symbols Nerd Font Mono" as the non-ASCII/fallback font) — installing it does not select it';

package/dist/core/runtime/nodes.d.ts

@@ -0,0 +1,140 @@
+import { type NodeMeta, type Mode, type Lifecycle, type LaunchSpec, type ManagedWorktree, type OutcomeDeliveryBinding, type ReviewBinding } from '../canvas/index.js';
+import { type CanvasDb } from '../canvas/db.js';
+/** Explicitly set the resolved install id. crtrd calls this once at boot,
+ *  immediately after `resolveInstallId()` — see crtrd.ts — so a provisioning
+ *  mismatch fails the daemon loudly at STARTUP rather than lazily on first
+ *  spawn. Exported for the daemon only; every other caller gets it lazily via
+ *  `installId()` below. */
+export declare function setInstallId(id: string): void;
+/** Raw time-sortable + random id shape — used for non-node opaque ids such as
+ *  focus ids (`f-…`) that are NOT canvas node identities and keep their
+ *  historical 2-segment shape (unstamped by the canvas-install id). */
+export declare function newJobId(): string;
+/** Generate a NODE id: `<install>-<time36>-<rand4hex>` (3 segments) — the
+ *  canvas-install id stamped onto the historical job-id shape, so every
+ *  minted node id is a globally-unique NAME that also names the canvas that
+ *  minted it (see the unified-chat/addressing design's "ID scheme"). crtrd is
+ *  the sole node minter. */
+export declare function newNodeId(): Promise<string>;
+/** Thrown when a caller-specified `--node-id` (or its API twin `node_id`)
+ *  already names a live node. Distinguishable from every other spawn failure
+ *  so a caller can treat it as "attach instead of create" per the unified
+ *  chat/addressing design's ensure semantics — never overwrite, never
+ *  double-spawn. Mapped to HTTP 409 in `src/daemon/api/map.ts`. */
+export declare class NodeIdConflictError extends Error {
+    readonly nodeId: string;
+    constructor(nodeId: string);
+}
+/** Best-effort preflight for a caller-supplied `--node-id`, run BEFORE any
+ *  worktree is allocated for it (`spawnChild` in spawn.ts) — so a malformed or
+ *  already-taken id fails before there is anything to leak/clean up. Format
+ *  validation here is authoritative (an id that fails it can never become
+ *  valid); the duplicate check is advisory only — a concurrent create can
+ *  still win the race between this check and the synchronous check-then-
+ *  create below, which remains the SOLE authoritative decider. */
+export declare function preflightNodeId(nodeId: string): Promise<void>;
+/** The root of a node's spine: walk the `parent` column up to `parent == null`.
+ *  Cycle-guarded (parents must not cycle, but never loop forever). Lives in the
+ *  node layer (not placement) so the env-builder and placement both reach it
+ *  without an import cycle — `CRTR_SUBTREE` is emitted as `rootOfSpine(nodeId)`
+ *  at every launch site. */
+export declare function rootOfSpine(nodeId: string): Promise<string>;
+export interface NodeContext {
+    nodeId: string | null;
+    kind: string | null;
+    mode: Mode | null;
+}
+/** Read the current node's identity from the environment. A spawned pi process
+ *  runs with CRTR_NODE_ID set; its own `crtr` invocations spawn children under
+ *  it by reading CRTR_NODE_ID as the parent. */
+export declare function currentNodeContext(): NodeContext;
+/** Whether a node's broker admits inbox mail only between agent runs: an
+ *  app-started run and its descendants, never a person's terminal node. */
+export declare function inboxBetweenTurns(meta: Pick<NodeMeta, 'run_id' | 'grantee'>): boolean;
+/** The env injected into a node's pi process. Self-gating extensions read
+ *  CRTR_KIND/CRTR_MODE to flip behavior on polymorph without a respawn; the
+ *  feed/inbox machinery reads CRTR_NODE_ID. */
+export declare function nodeEnv(meta: NodeMeta): Record<string, string>;
+export interface SpawnNodeOpts {
+    kind: string;
+    mode?: Mode;
+    lifecycle?: Lifecycle;
+    cwd: string;
+    name?: string;
+    /** Editor-label handle (2-4 word kebab-case) for the node's first prompt. */
+    description?: string;
+    /** Parent node id: the spine manager. Omit for a user-opened root. */
+    parent?: string | null;
+    /** Node that created this node. Unlike parent (manager) and spawnedBy
+     *  (audit provenance), it is the actor of `created`, so the parent is pushed
+     *  `created` only when someone else created the child.
+     *  Null/omitted means an external process. */
+    creator?: string | null;
+    /** Node acting when neither creator nor parent is (a node forking another). */
+    actor?: string | null;
+    /** Node whose watches the new node copies (`fork`, never in the tree). */
+    forkSourceNode?: string | null;
+    /** Who spawned me (the `spawned_by` provenance edge), when it differs from
+     *  `parent` — e.g. an independent root (parent=null) still records its
+     *  spawner. Defaults to `parent`. */
+    spawnedBy?: string | null;
+    /** Raw `--fork-from` operand retained for identity framing and audit. */
+    forkFrom?: string | null;
+    /** Resolved absolute source session file retained for pre-bind retries. */
+    forkSourceFile?: string | null;
+    /** Suppress the spawn-time parent→child ACTIVE subscription. Default true
+     *  (every existing caller keeps its edge). False gives ordinary canvas
+     *  placement with no wake path back to the parent. */
+    subscribe?: boolean;
+    /** Immutable review-companion provenance. Omit for every ordinary node. */
+    reviewBinding?: ReviewBinding | null;
+    /** New subscriptions this node opens default to passive when true. */
+    passiveDefault?: boolean;
+    /** Resolved pi launch recipe (from resolve(kind,mode)). */
+    launch?: LaunchSpec;
+    /** Caller-pinned model tier (ultra/strong/medium/light) that overrides the
+     *  persona default. Persisted to `meta.model_override` so polymorphs preserve
+     *  it. Omit to use the persona default. */
+    modelOverride?: string | null;
+    /** The profile-directory id (`<slug>-<id>`) this node runs under; null only
+     *  for historical root/no-profile nodes. Written to `meta.profile_id` and the
+     *  row, and mirrored into the pi process env as `CRTR_PROFILE_ID` by
+     *  `nodeEnv` — the runtime → resolver seam every downstream memory/gate
+     *  consumer reads. Callers resolve/validate the operand (via
+     *  `loadProfileManifest`) before it reaches here; this layer just persists the
+     *  already-resolved id. */
+    profile_id?: string | null;
+    /** Per-run scope allow-list. Omit to inherit the creating node's list. */
+    scopes?: string[];
+    /** Sticky isolation; an isolated ancestor cannot be overridden. */
+    isolated?: boolean;
+    /** Run identity set on an app root; managed children inherit it. */
+    run?: Pick<NodeMeta, 'grantee' | 'sub' | 'grant_id' | 'client_id' | 'metadata_json' | 'run_id' | 'event_cursor' | 'usage_json'>;
+    /** What caused this run, stored on its root node (`run.start`'s `Crtr-Caused-By`). */
+    causedBy?: string;
+    /** Additional rows committed atomically with the newborn node. */
+    withinCreate?: (db: CanvasDb, row: NodeMeta) => Promise<void> | void;
+    /** Managed worktree already created for this node, if any. */
+    managedWorktree?: ManagedWorktree;
+    /** Absolute wall-clock deadline persisted with the row at birth. */
+    deadlineAt?: string;
+    /** Delivery target persisted with the row before any broker can launch. */
+    outcomeDelivery?: OutcomeDeliveryBinding;
+    /** Runs after the create hook admitted the birth but before its row is written. */
+    beforeCreate?: () => void | Promise<void>;
+    /** Root id replaced by this birth (`/new` or recycle); null for all other births. */
+    replaces?: string | null;
+    /** Override the generated id — either an internally pre-allocated id
+     *  (worktree naming; always valid+fresh) or an external caller's explicit id
+     *  (`--node-id`), which is format-validated
+     *  and duplicate-rejected (`NodeIdConflictError`) here. */
+    nodeId?: string;
+}
+/** The node that owns the conversation a fork copies, or null when no node does. */
+export declare function forkSourceNode(sourceFile: string): Promise<NodeMeta | null>;
+/** Create a node on the canvas and wire its spawn-time edges.
+ *
+ *  For a child (parent given): the parent auto-subscribes ACTIVE to the child
+ *  (so it's woken when the child finishes), and a spawned_by audit edge is
+ *  recorded. For a root (no parent): no edges, resident by default. */
+export declare function spawnNode(opts: SpawnNodeOpts): Promise<NodeMeta>;