@north-light/crouter 0.3.235 → 0.3.237

package/dist/commands/sys/context/admin.js

@@ -0,0 +1,124 @@
+// `crtr sys context admin` — the interactive surface over the context system:
+// dial a configuration snapshot, watch every document's resolved rung across
+// the six events, and edit the surfaces, gates, and caps that decide it.
+// Mutations route through `memory edit` / `memory move` and the profile
+// manifest, never through direct file writes.
+import { resolve as resolvePath } from 'node:path';
+import { defineLeaf } from '../../../core/command.js';
+import { InputError } from '../../../core/io.js';
+import { ApiError } from '../../../api/index.js';
+import { cliClient } from '../../api-client.js';
+import { SURFACE_EVENTS } from '../../../core/substrate/schema.js';
+import { ambientMemoryTarget } from '../../../core/memory-resolver.js';
+import { resolveProfileOperand } from '../../../core/profiles/manifest.js';
+export const adminLeaf = defineLeaf({
+    name: 'admin',
+    description: 'browse and edit the context surface interactively',
+    whenToUse: 'you are shaping what agents load rather than answering one question about it — comparing snapshots, sweeping which documents fire where, and editing surfaces, gates, or caps in place',
+    help: {
+        name: 'sys context admin',
+        summary: 'interactive browser and editor for the memory context surface',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Open with the snapshot derived from this live node instead of the defaults.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Opening node kind. Defaults to the --node value, else `general`.' },
+            { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, constraint: 'Opening node mode. Defaults to `base`.' },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile id whose memory store and project-memory caps apply. Defaults to the selected profile.' },
+            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Directory the project stores resolve from. Defaults to the current directory.' },
+            { kind: 'flag', name: 'event', type: 'enum', choices: [...SURFACE_EVENTS], required: false, constraint: 'Opening event for the detail panel. Defaults to `boot`.' },
+        ],
+        output: [
+            { name: 'edited', type: 'array', required: false, constraint: 'Canonical names of the documents changed during the session; absent when nothing was changed.' },
+            { name: 'cap_changes', type: 'array', required: false, constraint: 'Profile project-memory caps changed during the session, each as store path and new rung; absent when none were.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Interactive: requires a TTY.',
+            'Edits memory documents through `memory edit` / `memory move` with rationale `editor` when you choose an edit action.',
+            'Writes profile project-memory caps to the profile manifest when you change one.',
+        ],
+    },
+    run: async (input) => {
+        if (!process.stdout.isTTY) {
+            throw new InputError({
+                error: 'not_a_tty',
+                message: 'sys context admin is interactive and needs a TTY',
+                next: 'Run it in a terminal, or use `crtr sys context resolve` and `crtr sys context doc` for scriptable reads.',
+            });
+        }
+        const node = await fetchNodeOrNull(input['node']?.trim() ?? '');
+        const ambient = ambientMemoryTarget();
+        const profileId = input['profile']?.trim();
+        const cwd = input['cwd']?.trim();
+        const seed = {
+            kind: input['kind']?.trim() || node?.kind || 'general',
+            mode: input['mode'] ?? node?.mode ?? 'base',
+            lifecycle: node?.lifecycle ?? 'terminal',
+            hasManager: node?.parent != null,
+            profileId: profileId === undefined || profileId === ''
+                ? (node?.profile_id ?? ambient.profileId)
+                : resolveProfileOperand(profileId).profileId,
+            cwd: cwd === undefined || cwd === '' ? (node?.cwd ?? ambient.cwd) : resolvePath(cwd),
+            nodeId: node?.node_id ?? null,
+            depth: node === null ? 0 : await spineDepth(node),
+            event: (input['event'] ?? 'boot'),
+            file: '',
+            docName: '',
+            command: '',
+        };
+        // Deferred so the page host, its terminal, and the whole TUI dependency
+        // chain load only for the interactive run — every other `sys context` leaf
+        // stays a plain read.
+        const { runContextAdmin } = await import('./admin/shell.js');
+        const result = await runContextAdmin(seed);
+        if (result === undefined)
+            return {};
+        return {
+            ...(result.edited.length > 0 ? { edited: result.edited } : {}),
+            ...(result.capChanges.length > 0
+                ? { cap_changes: result.capChanges.map((change) => ({ path: change.path, memory: change.memory })) }
+                : {}),
+        };
+    },
+    render: (r) => {
+        const edited = r['edited'] ?? [];
+        const caps = r['cap_changes'] ?? [];
+        if (edited.length === 0 && caps.length === 0)
+            return 'Closed the context admin with nothing changed.';
+        const lines = [
+            ...edited.map((name) => `- edited ${name}`),
+            ...caps.map((cap) => `- ceiling ${cap.path} → ${cap.memory}`),
+        ];
+        return lines.join('\n');
+    },
+});
+/** A `--node` id that no longer resolves seeds nothing rather than failing: the
+ *  page is useful without a live node, and the ids an agent has to hand are the
+ *  ones most likely to have been pruned. */
+async function fetchNodeOrNull(nodeId) {
+    if (nodeId === '')
+        return null;
+    try {
+        return await cliClient().getNode(nodeId);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404)
+            return null;
+        throw err;
+    }
+}
+/** Hops from a node up to its root orchestrator, walked through the API so this
+ *  leaf never reaches the canvas db. A pruned ancestor ends the walk. */
+async function spineDepth(node) {
+    const seen = new Set([node.node_id]);
+    let parent = node.parent;
+    let hops = 0;
+    while (parent != null && !seen.has(parent)) {
+        seen.add(parent);
+        hops += 1;
+        const next = await fetchNodeOrNull(parent);
+        if (next === null)
+            break;
+        parent = next.parent;
+    }
+    return hops;
+}

package/dist/commands/sys/context/doc.d.ts

@@ -0,0 +1 @@
+export declare const docLeaf: import("../../../core/command.js").LeafDef;

package/dist/commands/sys/context/doc.js

@@ -0,0 +1,196 @@
+// `crtr sys context doc` — the reverse question: for ONE document, everywhere
+// it surfaces and why. Authored surface entries plus a computed row per event
+// under a single configuration snapshot, from the same plan the live renderers
+// deliver from (`planDelivery`, src/core/substrate/plan.ts).
+import { defineLeaf } from '../../../core/command.js';
+import { realpathOrSelf } from '../../../core/fs-utils.js';
+import { resolveMemoryDocForTarget } from '../../../core/memory-resolver.js';
+import { InputError } from '../../../core/io.js';
+import { planDelivery } from '../../../core/substrate/plan.js';
+import { parseSubstrateDoc, SURFACE_EVENTS } from '../../../core/substrate/schema.js';
+import { buildSnapshot, cell, delivers, describeSubject, entryText, exclusionReason, gateText, optionalString, payloadFor, subjectSummary, } from './resolve.js';
+export const docLeaf = defineLeaf({
+    name: 'doc',
+    description: 'show one document\u2019s delivery across every surface event',
+    whenToUse: 'a document is reaching a node it should not, or failing to reach one it should — this says which event delivers it, at what rung, and what excluded it everywhere else',
+    help: {
+        name: 'sys context doc',
+        summary: 'show where one document delivers, at what rung, and what excludes it elsewhere',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Canonical document name, exactly as `crtr memory read` takes it.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Evaluate under this live node\u2019s configuration — derives kind, mode, lifecycle, has-manager, profile, and cwd from it.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Node kind of the synthetic subject. Defaults to the --node value, else `general`.' },
+            { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, constraint: 'Node mode of the synthetic subject. Defaults to `base`.' },
+            { kind: 'flag', name: 'lifecycle', type: 'enum', choices: ['terminal', 'resident'], required: false, constraint: 'Node lifecycle of the synthetic subject. Defaults to `terminal` for base, `resident` for orchestrator.' },
+            { kind: 'flag', name: 'has-manager', type: 'enum', choices: ['true', 'false'], required: false, constraint: 'Treat the subject as having a manager (a subscriber above it). Defaults to the --node value, else true.' },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile id whose memory store and project-memory caps apply. Defaults to the selected profile.' },
+            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Directory the project stores resolve from. Defaults to the current directory.' },
+            { kind: 'flag', name: 'event', type: 'enum', choices: [...SURFACE_EVENTS], required: false, constraint: 'Report only this event instead of all six.' },
+            { kind: 'flag', name: 'file', type: 'path', required: false, constraint: 'Payload for the read event: the file being read. Without it, no read entry matches.' },
+            { kind: 'flag', name: 'read-name', type: 'string', required: false, constraint: 'Payload for the memory-read event: the exact canonical name that read resolved to.' },
+            { kind: 'flag', name: 'command', type: 'string', required: false, constraint: 'Payload for the command and pre-command events: the command string.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'The document\u2019s canonical name.' },
+            { name: 'kind', type: 'string', required: true, constraint: 'knowledge or preference.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'node, project, profile, user, or builtin.' },
+            { name: 'store_path', type: 'string', required: true, constraint: 'Absolute path to the document file.' },
+            { name: 'project_memory_cap', type: 'string', required: true, constraint: 'The profile relationship\u2019s cap on this document\u2019s store; it binds at boot and workspace-open only.' },
+            { name: 'subject', type: 'object', required: true, constraint: 'The configuration snapshot every row was computed under.' },
+            { name: 'surfaces', type: 'array', required: true, constraint: 'The document\u2019s authored surface entries: event, match globs, gate, rung.' },
+            { name: 'events', type: 'array', required: true, constraint: 'One row per event: event, delivers, authored_rung, capped_rung, final_rung, doc_gate, entry_gate, matched_entry, winner, shadowed_by, and — when the event\u2019s corpus does not carry this document at all — excluded saying so.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const snapshot = await buildSnapshot(input);
+        const doc = resolveDoc(input['name'], snapshot.target);
+        const events = optionalString(input['event']) === null
+            ? [...SURFACE_EVENTS]
+            : [input['event']];
+        const flags = {
+            file: optionalString(input['file']),
+            readName: optionalString(input['readName']),
+            command: optionalString(input['command']),
+        };
+        const targetPath = realpathOrSelf(doc.path);
+        const recordPathCache = new Map();
+        const rows = events.map((event) => {
+            const plan = planDelivery(snapshot.subject, snapshot.target, event, payloadFor(event, flags, snapshot.target));
+            return eventRow(event, findRecord(plan.docs, targetPath, recordPathCache));
+        });
+        return {
+            name: doc.name,
+            kind: doc.kind,
+            scope: doc.scope,
+            store_path: doc.path,
+            project_memory_cap: doc.projectMemory,
+            subject: subjectSummary(snapshot.subject),
+            surfaces: doc.surfaces.map(surfaceRow),
+            events: rows,
+        };
+    },
+    render: (result) => renderDoc(result),
+});
+/** The document the name addresses under this snapshot's store chain — the same
+ *  winner `crtr memory read` would open. A document whose frontmatter does not
+ *  parse into the substrate schema has no surface behavior to report. */
+function resolveDoc(name, target) {
+    const source = resolveMemoryDocForTarget(name, target);
+    const doc = parseSubstrateDoc(source);
+    if (doc === null) {
+        throw new InputError({
+            error: 'invalid_field',
+            message: `document is not a substrate document: ${source.path}`,
+            field: 'name',
+            next: 'Give the document valid frontmatter (`kind` and `when-and-why-to-read`) with `crtr memory edit`.',
+        });
+    }
+    return doc;
+}
+/** The plan record for this exact physical document. Identity is the file, not
+ *  the name: a nearer store may hold a different document under the same name,
+ *  and that one is the shadower, not this row's subject. */
+function findRecord(records, targetPath, pathCache) {
+    return records.find((record) => {
+        let recordPath = pathCache.get(record.storePath);
+        if (recordPath === undefined) {
+            recordPath = realpathOrSelf(record.storePath);
+            pathCache.set(record.storePath, recordPath);
+        }
+        return recordPath === targetPath;
+    }) ?? null;
+}
+function surfaceRow(entry) {
+    return {
+        event: entry.on,
+        match: entry.match === undefined ? null : entry.match.join(', '),
+        match_frontmatter: entry.matchFrontmatter !== undefined,
+        gate: entry.gate !== undefined,
+        at: entry.at,
+    };
+}
+function eventRow(event, record) {
+    if (record === null) {
+        return {
+            event,
+            delivers: false,
+            authored_rung: 'none',
+            capped_rung: 'none',
+            final_rung: 'none',
+            doc_gate: null,
+            entry_gate: null,
+            matched_entry: null,
+            winner: false,
+            shadowed_by: null,
+            excluded: `this event\u2019s corpus does not carry the document (${corpusNote(event)})`,
+        };
+    }
+    return {
+        event,
+        delivers: delivers(record),
+        authored_rung: record.authoredRung,
+        capped_rung: record.cappedRung,
+        final_rung: record.finalRung,
+        doc_gate: gateText(record.docGate),
+        entry_gate: record.entryGate === null ? null : gateText(record.entryGate),
+        matched_entry: entryText(record.matchedEntry),
+        winner: record.winner,
+        shadowed_by: record.shadowedBy === null ? null : `${record.shadowedBy.scope}:${record.shadowedBy.path}`,
+        excluded: delivers(record) ? null : exclusionReason(record),
+    };
+}
+function corpusNote(event) {
+    if (event === 'workspace-open')
+        return 'workspace-open sees project stores only';
+    if (event === 'memory-read')
+        return 'the document being read never delivers to itself';
+    return 'it is excluded from this event\u2019s document set';
+}
+function renderDoc(result) {
+    const lines = [
+        `# ${result.name}`,
+        '',
+        `- kind: ${result.kind}`,
+        `- scope: ${result.scope}`,
+        `- path: ${result.store_path}`,
+        `- project-memory cap: ${result.project_memory_cap} (binds at boot and workspace-open only)`,
+        '',
+        `subject: ${describeSubject(result.subject)}`,
+        '',
+        '## Authored surfaces',
+        '',
+        renderSurfaces(result.surfaces),
+        '',
+        '## Delivery per event',
+        '',
+        renderEvents(result.events),
+    ];
+    return lines.join('\n');
+}
+function renderSurfaces(surfaces) {
+    if (surfaces.length === 0) {
+        return 'None. The document authors no surface entry, so it only appears in its directory listing.';
+    }
+    return table(['event', 'at', 'match', 'match-frontmatter', 'gate'], surfaces.map((s) => [s.event, s.at, s.match ?? '—', s.match_frontmatter ? 'yes' : '—', s.gate ? 'yes' : '—']));
+}
+function renderEvents(events) {
+    return table(['event', 'delivers', 'authored', 'capped', 'final', 'matched', 'gate', 'why not'], events.map((e) => [
+        e.event,
+        e.delivers ? 'yes' : 'no',
+        e.authored_rung,
+        e.capped_rung,
+        e.final_rung,
+        e.matched_entry ?? '—',
+        e.doc_gate ?? '—',
+        e.excluded ?? '—',
+    ]));
+}
+function table(cols, rows) {
+    return [
+        `| ${cols.join(' | ')} |`,
+        `| ${cols.map(() => '---').join(' | ')} |`,
+        ...rows.map((r) => `| ${r.map(cell).join(' | ')} |`),
+    ].join('\n');
+}

package/dist/commands/sys/context/prompt-review.d.ts

@@ -0,0 +1 @@
+export declare const promptReviewLeaf: import("../../../core/command.js").LeafDef;

package/dist/commands/sys/{prompt-review.js → context/prompt-review.js}

@@ -1,18 +1,18 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { defineLeaf } from '../../core/command.js';
-import { InputError, readStdinRaw } from '../../core/io.js';
-import { userScopeRoot } from '../../core/scope.js';
-import { ApiError } from '../../api/index.js';
-import { cliClient } from '../api-client.js';
-import { readMergedLaunchConfig, subKindsAvailableTo } from '../../core/config.js';
-import { LAUNCH_SYSTEM_PROMPT } from '../../core/runtime/launch-prompt.js';
+import { defineLeaf } from '../../../core/command.js';
+import { InputError, readStdinRaw } from '../../../core/io.js';
+import { userScopeRoot } from '../../../core/scope.js';
+import { ApiError } from '../../../api/index.js';
+import { cliClient } from '../../api-client.js';
+import { readMergedLaunchConfig, subKindsAvailableTo } from '../../../core/config.js';
+import { LAUNCH_SYSTEM_PROMPT } from '../../../core/runtime/launch-prompt.js';
 // De-barreled imports: substrate/index.js re-exports subject.js (canvas-db), so
 // this CLI leaf imports the PURE render fns from render.js and the pure subject
 // fields from subject-fields.js/schema.js directly, never the barrel. Spine
 // depth is computed via the API (spineDepthViaApi), not subject.js's spineDepth.
-import { renderPreferencesForSubject, renderKnowledgeForSubject } from '../../core/substrate/render.js';
-import { scopeForCwd, profileNameFor } from '../../core/substrate/subject-fields.js';
+import { renderPreferencesForSubject, renderKnowledgeForSubject } from '../../../core/substrate/render.js';
+import { scopeForCwd, profileNameFor } from '../../../core/substrate/subject-fields.js';
 function resolveLifecycle(mode, lifecycle) {
     if (lifecycle !== undefined)
         return lifecycle;
@@ -245,7 +245,7 @@ export const promptReviewLeaf = defineLeaf({
     description: 'inspect an assembled prompt and export review notes',
     whenToUse: 'you want to inspect a composed persona prompt for a kind/mode combo, compare the space around it, or export review notes back to source files',
     help: {
-        name: 'sys prompt-review',
+        name: 'sys context prompt-review',
         summary: 'inspect an assembled prompt and export review notes',
         params: [
             { kind: 'positional', name: 'action', type: 'string', required: false, constraint: 'Optional subcommand: export. Omit for the assembled prompt contract.' },

package/dist/commands/sys/context/resolve.d.ts

@@ -0,0 +1,55 @@
+import { type MemoryTarget } from '../../../core/memory-resolver.js';
+import { type DeliveryPayload, type DeliveryRecord, type GateOutcome } from '../../../core/substrate/plan.js';
+import { type Rung, type SurfaceEntry, type SurfaceEvent } from '../../../core/substrate/schema.js';
+import { type NodeConfigSubject } from '../../../core/substrate/subject-fields.js';
+export declare const resolveLeaf: import("../../../core/command.js").LeafDef;
+export interface ContextSnapshot {
+    subject: NodeConfigSubject;
+    target: MemoryTarget;
+    /** `--node` named an id the daemon does not have; the subject is synthetic. */
+    nodeMissing: boolean;
+}
+/** Build the subject and store target from `--node` and the axis flags. A flag
+ *  always wins over the value derived from the node, so a live node is a
+ *  starting point an engineer can dial away from. */
+export declare function buildSnapshot(input: Record<string, unknown>): Promise<ContextSnapshot>;
+/** The three payload-carrying flags, named once so each leaf can map its own
+ *  flag spelling onto them (`doc` spends its `name` on the document itself). */
+export interface PayloadFlags {
+    file: string | null;
+    readName: string | null;
+    command: string | null;
+}
+/** The event's match payload from the flags that carry it. An event invoked
+ *  without its payload matches nothing — the planner's own contract. */
+export declare function payloadFor(event: SurfaceEvent, flags: PayloadFlags, target: MemoryTarget): DeliveryPayload;
+export declare function subjectSummary(subject: NodeConfigSubject): Record<string, unknown>;
+export declare function optionalString(value: unknown): string | null;
+export interface DocRow {
+    name: string;
+    kind: string;
+    scope: string;
+    store_path: string;
+    authored_rung: Rung;
+    project_memory_cap: Rung | null;
+    capped_rung: Rung;
+    final_rung: Rung;
+    winner: boolean;
+    shadowed_by: string | null;
+    doc_gate: string;
+    entry_gate: string | null;
+    matched_entry: string | null;
+    excluded?: string;
+}
+/** A document delivers when it won its canonical name AND resolved to a rung
+ *  above the no-delivery floor — boot keeps rung-`none` winners in the plan so
+ *  the catalog can still count them. */
+export declare function delivers(record: DeliveryRecord): boolean;
+export declare function docRow(record: DeliveryRecord, includeAll: boolean): DocRow;
+export declare function gateText(gate: GateOutcome): string;
+export declare function entryText(entry: SurfaceEntry | null): string | null;
+/** Why a considered document delivers nothing, in the order the planner applies
+ *  its checks — the first failing one is the answer an engineer acts on. */
+export declare function exclusionReason(record: DeliveryRecord): string;
+export declare function describeSubject(subject: Record<string, unknown>): string;
+export declare function cell(v: unknown): string;