@north-light/api 0.3.580 → 0.3.588

package/dist/commands/sys/context/admin/list-view.js

@@ -0,0 +1,170 @@
+// The list's view model: which documents a question selects, how they group,
+// and how much of each group loads. Pure — no terminal, no colour, no width — so the
+// rail's counts and the list's rows are computed from the same call.
+import { fuzzyMatch } from '../../../../core/tui/fuzzy.js';
+/** The owner types a document can belong to. */
+export const OWNER_TYPES = ['node', 'user', 'profile', 'repo', 'app'];
+export const NO_FILTERS = { rung: 'any', origin: 'any', kind: 'any', state: 'any', query: '' };
+/** Documents whose canonical name carries no `/` and owns no directory share
+ *  one leading section rather than becoming a crowd of one-member groups. */
+const LEADING_KEY = '';
+const LEADING_LABEL = 'top level';
+/** Every group key the rows can produce — one per proper name prefix, since a
+ *  prefix exists only because something sits under it — so collapse state can
+ *  drop the keys a re-plan removed instead of accumulating them. The leading
+ *  section is a key only when a name with no `/` owns no directory, which is
+ *  exactly when it is not itself one of those prefixes. */
+export function groupKeysOf(rows) {
+    const keys = new Set();
+    const unslashed = [];
+    for (const row of rows) {
+        if (row.name.includes('/')) {
+            for (let cut = row.name.indexOf('/'); cut >= 0; cut = row.name.indexOf('/', cut + 1)) {
+                keys.add(row.name.slice(0, cut));
+            }
+        }
+        else
+            unslashed.push(row.name);
+    }
+    if (unslashed.some((name) => !keys.has(name)))
+        keys.add(LEADING_KEY);
+    return keys;
+}
+/** The lines to draw, in corpus order: the leading section, then each directory
+ *  in order of first appearance, each recursing into its own members only when
+ *  it is open. A live query force-expands every directory, which is exactly the
+ *  ancestor chain of every surviving match, without touching `expanded` — so
+ *  clearing the query restores what the user collapsed. */
+export function buildListView(rows, filters, expanded, event) {
+    const root = { key: '', segment: '', depth: -1, children: new Map(), selves: [] };
+    for (const row of rows) {
+        if (!passes(row, row.records.get(event), filters))
+            continue;
+        let dir = root;
+        for (const segment of row.name.split('/')) {
+            let child = dir.children.get(segment);
+            if (child === undefined) {
+                child = {
+                    key: dir.depth < 0 ? segment : `${dir.key}/${segment}`,
+                    segment,
+                    depth: dir.depth + 1,
+                    children: new Map(),
+                    selves: [],
+                };
+                dir.children.set(segment, child);
+            }
+            dir = child;
+        }
+        dir.selves.push(row);
+    }
+    const leading = [];
+    const dirs = [];
+    for (const child of root.children.values()) {
+        if (child.children.size === 0)
+            leading.push(...child.selves);
+        else
+            dirs.push(child);
+    }
+    const lines = [];
+    if (leading.length > 0) {
+        const open = filters.query !== '' || expanded.has(LEADING_KEY);
+        lines.push({
+            kind: 'group',
+            key: LEADING_KEY,
+            label: LEADING_LABEL,
+            depth: 0,
+            ...rollup(leading, event),
+            expanded: open,
+            first: leading[0],
+        });
+        if (open)
+            for (const row of leading)
+                lines.push(docLine(row, row.name, 1, event));
+    }
+    for (const dir of dirs)
+        emit(dir, filters, expanded, event, lines);
+    return lines;
+}
+/** A directory's rows in drawn order: its own document first, then each child
+ *  segment's subtree — so the head of the list is also the document the header
+ *  hands the dossier. */
+function subtree(dir, out = []) {
+    out.push(...dir.selves);
+    for (const child of dir.children.values())
+        subtree(child, out);
+    return out;
+}
+function emit(dir, filters, expanded, event, lines) {
+    if (dir.children.size === 0) {
+        for (const row of dir.selves)
+            lines.push(docLine(row, dir.segment, dir.depth, event));
+        return;
+    }
+    const members = subtree(dir);
+    const open = filters.query !== '' || expanded.has(dir.key);
+    lines.push({
+        kind: 'group',
+        key: dir.key,
+        label: `${dir.segment}/`,
+        depth: dir.depth,
+        ...rollup(members, event),
+        expanded: open,
+        first: members[0],
+    });
+    if (!open)
+        return;
+    // A directory that is also a document is a header plus a row, never one row
+    // doing both: the header is a pure rollup that expands, and the document sits
+    // inside it under its own name — no trailing slash — like any other member.
+    for (const self of dir.selves)
+        lines.push(docLine(self, dir.segment, dir.depth + 1, event));
+    for (const child of dir.children.values())
+        emit(child, filters, expanded, event, lines);
+}
+function docLine(row, label, depth, event) {
+    return { kind: 'doc', key: row.key, row, label, depth };
+}
+function rollup(members, event) {
+    const rungs = { name: 0, preview: 0, content: 0 };
+    for (const row of members) {
+        const record = row.records.get(event);
+        if (record !== undefined && record.finalRung !== 'none')
+            rungs[record.finalRung] += 1;
+    }
+    return { docs: members.length, rungs };
+}
+function passes(row, record, filters) {
+    if (filters.rung !== 'any') {
+        const rung = record?.finalRung ?? 'none';
+        if (filters.rung === 'silent' ? rung !== 'none' : rung !== filters.rung)
+            return false;
+    }
+    if (filters.origin !== 'any' && ownerTypeOf(row.anchor) !== filters.origin)
+        return false;
+    if (filters.kind !== 'any' && row.anchor.doc.kind !== filters.kind)
+        return false;
+    if (filters.state !== 'any' && !inState(record, filters.state))
+        return false;
+    if (filters.query !== '' && !fuzzyMatch(filters.query, row.name))
+        return false;
+    return true;
+}
+/** `user` is the person owner; every other facet is the owner object's type. */
+export function ownerTypeOf(record) {
+    return record.doc.owner.type === 'person' ? 'user' : record.doc.owner.type;
+}
+/** `gated`: a rule for this activity exists and its `if` refused the node. */
+function inState(record, state) {
+    if (record === undefined)
+        return state === 'no-rule';
+    switch (state) {
+        case 'delivering':
+            return record.finalRung !== 'none';
+        case 'gated':
+            return record.matchedRule === null && record.ruleGate !== null && !record.ruleGate.pass;
+        case 'shadowed':
+            return record.shadowedBy !== null;
+        case 'no-rule':
+            return record.authoredRules.length === 0;
+    }
+}

package/dist/commands/sys/context/admin/model.d.ts

@@ -0,0 +1,123 @@
+import type { DeliveryRuleDTO } from '../../../../api/dto/docs.js';
+import type { NodeConfigSubject } from '../../../../core/substrate/subject-fields.js';
+import { type ContextSnapshot, type PlanRecord, type PlanRule, type PlannedEvent } from '../resolve.js';
+/** The state an agent-engineer dials. Every axis feeds either the rule `if`
+ *  subject or the reader (cwd → repos, profile → limits), and changing one
+ *  re-plans every activity. */
+export interface Snapshot {
+    kind: string;
+    mode: 'base' | 'orchestrator';
+    lifecycle: 'terminal' | 'resident';
+    hasManager: boolean;
+    /** Profile id; null for no profile. */
+    profileId: string | null;
+    cwd: string;
+    /** The live node the page opened on, or null. */
+    nodeId: string | null;
+    grantee?: string;
+    depth: number;
+    event: PlannedEvent;
+    /** `file-read` payload — the file that was read. */
+    file: string;
+    /** `document-read` payload — the document read. */
+    docName: string;
+    /** `command` / `pre-command` payload. */
+    command: string;
+    /** The live node's own cwd and profile: while the snapshot keeps both, the
+     *  dry run reads the node itself, so its own documents stay in view. */
+    seed: {
+        cwd: string;
+        profileId: string | null;
+    } | null;
+}
+/** One profile the rail can cycle through. */
+export interface ProfileChoice {
+    id: string;
+    name: string;
+}
+/** A rule as the dry run returns it: the row fields over JSON. */
+export interface AdminRule extends PlanRule {
+    position?: number;
+}
+/** The delivery document as the dry run serializes it (bodies are not carried). */
+export interface AdminDoc {
+    object: {
+        id: string;
+        type: string;
+        name: string;
+    };
+    owner: {
+        id: string;
+        type: string;
+        name: string;
+    };
+    ownerHandle: string;
+    ownNode: boolean;
+    /** A package document: an installed plugin's or crtr's own, read-only here. */
+    shipped: boolean;
+    kind: 'knowledge' | 'preference';
+    name: string;
+    displayName: string;
+    preview: string;
+    unlisted: boolean;
+    rules: AdminRule[];
+}
+export type AdminRecord = Omit<PlanRecord, 'doc' | 'shadowedBy'> & {
+    doc: AdminDoc;
+    shadowedBy: AdminDoc | null;
+};
+export interface AdminPlan {
+    subject: NodeConfigSubject | null;
+    docs: AdminRecord[];
+}
+/** Which payload axis an activity reads, so the rail offers exactly the one
+ *  field that can make the current activity match anything. */
+export declare function payloadAxisFor(event: PlannedEvent): 'file' | 'docName' | 'command' | null;
+/** The dry-run request a snapshot stands for: the live node as it is (the
+ *  subject axes as overrides) while cwd and profile are still the node's own,
+ *  else a node that does not exist, started from the live node when there is one. */
+export declare function contextSnapshotOf(snapshot: Snapshot): ContextSnapshot;
+/** Every activity's plan for one snapshot, fetched from the daemon. The
+ *  focused activity is asked for first and the rest follow; a plan that lands
+ *  after the snapshot changed is dropped. */
+export declare class PlanSet {
+    private snapshot;
+    private readonly onChange;
+    private readonly plans;
+    /** Plans read for the current documents; a plan outside it is stale and is
+     *  shown only until its replacement lands. */
+    private readonly fresh;
+    private readonly pending;
+    private generation;
+    /** The last dry run's refusal, shown in place of the list. */
+    error: string | undefined;
+    constructor(snapshot: Snapshot, onChange: () => void);
+    setSnapshot(snapshot: Snapshot): void;
+    /** Drop every plan — the snapshot changed, so none of them describes it. */
+    invalidate(): void;
+    /** Re-read every plan after a write changed a document they were read from,
+     *  keeping the old plans on screen until each replacement lands. */
+    refresh(): void;
+    dispose(): void;
+    peek(event: PlannedEvent): AdminPlan | undefined;
+    /** Fetch the focused activity, then every other one. */
+    warm(first: PlannedEvent): void;
+    private fetch;
+}
+/** What one document does in one activity. */
+export type DeliveryState = 'delivers' | 'capped' | 'gated' | 'shadowed' | 'silent';
+export declare function deliveryStateOf(record: AdminRecord | undefined): DeliveryState;
+/** The word the list prints for one document's state, and its tone. A delivery
+ *  names the level it arrives at, warning-toned when the profile limit lowered
+ *  it; a document that does not load prints nothing unless its silence has a
+ *  name the page can act on — `gated` or `shadowed`. */
+export declare function stateLabel(record: AdminRecord | undefined, state: DeliveryState): {
+    text: string;
+    tone: 'success' | 'warning' | 'muted';
+};
+export declare const DELIVER_LEVELS: ("name" | "preview" | "content")[];
+/** A rule back in the shape `PATCH /v1/docs/:ref` takes. */
+export declare function ruleToDTO(rule: AdminRule): DeliveryRuleDTO;
+/** One rule as a single readable row. */
+export declare function describeRule(rule: AdminRule): string;
+export declare function plural(count: number, one: string, many: string): string;

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

@@ -0,0 +1,179 @@
+// The read model behind `crtr sys context admin`: the configuration snapshot
+// the page dials, the per-activity delivery plans it reads from the daemon's
+// dry run, and the vocabulary both the list and the dossier read from.
+//
+// Every plan comes from `POST /v1/delivery/dry-run` — the same plan and render
+// live delivery uses — so the page can never report a delivery the runtime
+// would not make, and it never reads the canvas database or a document file.
+import { resolve as resolvePath } from 'node:path';
+import { RUNGS, rungRank } from '../../../../core/substrate/schema.js';
+import { PLANNED_EVENTS, dryRun } from '../resolve.js';
+/** Which payload axis an activity reads, so the rail offers exactly the one
+ *  field that can make the current activity match anything. */
+export function payloadAxisFor(event) {
+    if (event === 'file-read')
+        return 'file';
+    if (event === 'document-read')
+        return 'docName';
+    if (event === 'command' || event === 'pre-command')
+        return 'command';
+    return null;
+}
+/** The dry-run request a snapshot stands for: the live node as it is (the
+ *  subject axes as overrides) while cwd and profile are still the node's own,
+ *  else a node that does not exist, started from the live node when there is one. */
+export function contextSnapshotOf(snapshot) {
+    const override = {
+        kind: snapshot.kind,
+        mode: snapshot.mode,
+        lifecycle: snapshot.lifecycle,
+        hasManager: snapshot.hasManager,
+        orchestration: { depth: snapshot.depth },
+    };
+    const seed = snapshot.seed;
+    if (snapshot.nodeId !== null && seed !== null && seed.cwd === snapshot.cwd && seed.profileId === snapshot.profileId) {
+        return { nodeId: snapshot.nodeId, hypothetical: null, override, nodeMissing: false };
+    }
+    const hypothetical = {
+        cwd: snapshot.cwd,
+        profile: snapshot.profileId,
+        ...(snapshot.grantee === undefined ? {} : { grantee: snapshot.grantee }),
+        kind: snapshot.kind,
+        mode: snapshot.mode,
+        lifecycle: snapshot.lifecycle,
+        has_manager: snapshot.hasManager,
+        depth: snapshot.depth,
+    };
+    return { nodeId: snapshot.nodeId, hypothetical, override: {}, nodeMissing: false };
+}
+function payloadOf(snapshot, event) {
+    if (event === 'file-read')
+        return snapshot.file === '' ? undefined : resolvePath(snapshot.cwd, snapshot.file);
+    if (event === 'document-read')
+        return snapshot.docName === '' ? undefined : snapshot.docName;
+    if (event === 'command' || event === 'pre-command')
+        return snapshot.command === '' ? undefined : snapshot.command;
+    return undefined;
+}
+/** Every activity's plan for one snapshot, fetched from the daemon. The
+ *  focused activity is asked for first and the rest follow; a plan that lands
+ *  after the snapshot changed is dropped. */
+export class PlanSet {
+    snapshot;
+    onChange;
+    plans = new Map();
+    /** Plans read for the current documents; a plan outside it is stale and is
+     *  shown only until its replacement lands. */
+    fresh = new Set();
+    pending = new Set();
+    generation = 0;
+    /** The last dry run's refusal, shown in place of the list. */
+    error;
+    constructor(snapshot, onChange) {
+        this.snapshot = snapshot;
+        this.onChange = onChange;
+    }
+    setSnapshot(snapshot) {
+        this.snapshot = snapshot;
+        this.invalidate();
+    }
+    /** Drop every plan — the snapshot changed, so none of them describes it. */
+    invalidate() {
+        this.plans.clear();
+        this.refresh();
+    }
+    /** Re-read every plan after a write changed a document they were read from,
+     *  keeping the old plans on screen until each replacement lands. */
+    refresh() {
+        this.generation += 1;
+        this.fresh.clear();
+        this.pending.clear();
+        this.error = undefined;
+    }
+    dispose() {
+        this.generation += 1;
+    }
+    peek(event) {
+        return this.plans.get(event);
+    }
+    /** Fetch the focused activity, then every other one. */
+    warm(first) {
+        this.fetch(first);
+        for (const event of PLANNED_EVENTS)
+            this.fetch(event);
+    }
+    fetch(event) {
+        if (this.fresh.has(event) || this.pending.has(event))
+            return;
+        this.pending.add(event);
+        const generation = this.generation;
+        void dryRun(contextSnapshotOf(this.snapshot), event, payloadOf(this.snapshot, event)).then(({ plan }) => {
+            if (generation !== this.generation)
+                return;
+            this.pending.delete(event);
+            this.plans.set(event, { subject: plan.subject, docs: plan.docs });
+            this.fresh.add(event);
+            this.onChange();
+        }, (error) => {
+            if (generation !== this.generation)
+                return;
+            this.pending.delete(event);
+            this.plans.set(event, { subject: null, docs: [] });
+            this.fresh.add(event);
+            this.error = error instanceof Error ? error.message : String(error);
+            this.onChange();
+        });
+    }
+}
+export function deliveryStateOf(record) {
+    if (record === undefined)
+        return 'silent';
+    if (record.shadowedBy !== null)
+        return 'shadowed';
+    if (record.finalRung !== 'none') {
+        return rungRank(record.finalRung) < rungRank(record.authoredRung) ? 'capped' : 'delivers';
+    }
+    if (record.authoredRung !== 'none')
+        return 'capped';
+    if (record.matchedRule === null && record.ruleGate !== null && !record.ruleGate.pass)
+        return 'gated';
+    return 'silent';
+}
+/** The word the list prints for one document's state, and its tone. A delivery
+ *  names the level it arrives at, warning-toned when the profile limit lowered
+ *  it; a document that does not load prints nothing unless its silence has a
+ *  name the page can act on — `gated` or `shadowed`. */
+export function stateLabel(record, state) {
+    if (state === 'gated')
+        return { text: 'gated', tone: 'muted' };
+    if (state === 'shadowed')
+        return { text: 'shadowed', tone: 'muted' };
+    if (record === undefined || record.finalRung === 'none')
+        return { text: '', tone: 'muted' };
+    return { text: record.finalRung, tone: state === 'capped' ? 'warning' : 'success' };
+}
+export const DELIVER_LEVELS = RUNGS.filter((rung) => rung !== 'none');
+/** A rule back in the shape `PATCH /v1/docs/:ref` takes. */
+export function ruleToDTO(rule) {
+    return {
+        on: rule.on,
+        ...(rule.match === undefined ? {} : { match: rule.match }),
+        ...(rule.matchFrontmatter === undefined ? {} : { match_frontmatter: rule.matchFrontmatter }),
+        ...(rule.if === undefined ? {} : { if: rule.if }),
+        deliver: rule.deliver,
+    };
+}
+/** One rule as a single readable row. */
+export function describeRule(rule) {
+    const parts = [rule.on];
+    if (rule.match !== undefined && rule.match.length > 0)
+        parts.push(rule.match.join(' | '));
+    if (rule.matchFrontmatter !== undefined)
+        parts.push(`fm ${JSON.stringify(rule.matchFrontmatter)}`);
+    if (rule.if !== undefined)
+        parts.push(`if ${JSON.stringify(rule.if)}`);
+    return `${parts.join('  ')} → ${rule.deliver}`;
+}
+export function plural(count, one, many) {
+    return `${count} ${count === 1 ? one : many}`;
+}

package/dist/commands/sys/context/admin/rail-panel.d.ts

@@ -0,0 +1,84 @@
+import { type PlannedEvent } from '../resolve.js';
+import { type ProfileChoice, type Snapshot } from './model.js';
+import { type Filters } from './list-view.js';
+type SurfaceEvent = PlannedEvent;
+export type AxisId = 'event' | 'payload' | 'kind' | 'mode' | 'lifecycle' | 'manager' | 'depth' | 'profile' | 'cwd';
+export interface Axis {
+    id: AxisId;
+    label: string;
+    value: string;
+    /** Free-text axes open a field; the rest cycle in place. */
+    typed: boolean;
+}
+export type FacetId = 'rung' | 'origin' | 'kind' | 'state' | 'query';
+export interface Facet {
+    id: FacetId;
+    label: string;
+    value: string;
+    /** The query is typed; every other facet cycles through a closed set. */
+    typed: boolean;
+}
+/** The FILTERS rows for one filter value. `doc kind` is spelled out because the
+ *  snapshot above it dials the NODE's kind. */
+export declare function facetsOf(filters: Filters): Facet[];
+export declare function cycleFacet(filters: Filters, id: FacetId, delta: number): Filters;
+/** The configuration rows for a snapshot. The event and its payload are not
+ *  here — they belong to the EVENTS section, where the payload sits under the
+ *  count it explains. */
+export declare function axesOf(snapshot: Snapshot, profileName: string): Axis[];
+/** The payload field for the dialled event, or nothing when the event reads no
+ *  payload — on boot there is nothing it could change. It renders inside the
+ *  EVENTS section, directly under the count it explains. */
+export declare function payloadRowOf(snapshot: Snapshot): Axis | undefined;
+/** Cycle one enum axis, returning the changed snapshot. A typed axis is never
+ *  cycled — the shell opens a field for it instead. */
+export declare function cycleAxis(snapshot: Snapshot, id: AxisId, delta: number, profiles?: readonly ProfileChoice[]): Snapshot;
+/** Apply a typed axis's submitted value. */
+export declare function setTypedAxis(snapshot: Snapshot, id: AxisId, value: string): Snapshot;
+/** The value a typed axis's field is seeded with. */
+export declare function typedAxisValue(snapshot: Snapshot, id: AxisId): string;
+/** One activity as the rail states it: how many documents it delivers, and
+ *  whether it is the one the page is planning. `delivers` is undefined while
+ *  that event's plan is still warming. */
+export interface EventRow {
+    event: SurfaceEvent;
+    delivers: number | undefined;
+    dialled: boolean;
+}
+/** Every selectable rail row in drawn order: the events, the dialled event's
+ *  payload field directly under it, the configuration axes, then the filter
+ *  facets. One list, so the shell's single index is also the reading order. */
+export type RailRow = {
+    kind: 'event';
+    event: EventRow;
+} | {
+    kind: 'axis';
+    axis: Axis;
+    indent: boolean;
+} | {
+    kind: 'facet';
+    facet: Facet;
+};
+/** A rail row's identity, which the shell holds the cursor by. The list's
+ *  composition changes whenever the dialled event moves the payload row, so an
+ *  offset kept across that change points at a different row. */
+export declare function railRowKey(row: RailRow): string;
+/** What enter does on a rail row: an event dials it, a typed row opens its
+ *  field, and every other row hands the keyboard to the documents. Space does
+ *  the same thing on the first two and cycles the value on the last. */
+export declare function railEnter(row: RailRow | undefined): 'dial' | 'edit' | 'documents';
+export declare function railRowsOf(events: EventRow[], payload: Axis | undefined, axes: Axis[], facets: Facet[]): RailRow[];
+/** All three sections as one column. `index` runs over `rows`, while the
+ *  section headings and the blank rows between them are drawn but never
+ *  selectable. */
+export declare function renderRail(opts: {
+    rows: RailRow[];
+    index: number;
+    width: number;
+    height: number;
+    focused: boolean;
+    /** Documents the filters select, out of the whole corpus. */
+    matched: number;
+    total: number;
+}): string[];
+export {};