@north-light/api 0.0.0 → 0.3.414

package/dist/core/render.js

@@ -0,0 +1,138 @@
+// Default stdout rendering: the result a leaf returns is written FOR the model
+// to act on, not as data to parse. Output is a continuation of the agent's
+// prompt — PLAIN MARKDOWN, no XML wrapper. Scalars list as `- name: value`
+// bullets in output-schema order, prose fields render as paragraphs, and arrays
+// become a count lead-in plus a markdown table (objects) or bullets (scalars).
+// The raw JSON object is still available behind the `--json` global for tooling.
+//
+// A leaf may hand `defineLeaf` a bespoke `render(result)` for instruction-shaped
+// output that leads with the outcome (see `node new`, `push`).
+// Everything else falls through to the schema-driven generic renderer here, so
+// every command obeys the markdown paradigm without a hand-written renderer.
+// `renderError` is the one sanctioned exception: a failure is a different domain
+// from a result, so it keeps its `<error>` block.
+// Field names whose value is prose the agent reads, not a scalar it keys on —
+// these always render as their own paragraph, never as a `- name: value` bullet.
+const PROSE_FIELDS = new Set([
+    'follow_up', 'digest', 'message', 'next', 'result', 'content', 'body', 'guide',
+    'summary', 'note', 'reason', 'detail', 'details', 'hint', 'instruction',
+    'instructions', 'prompt', 'roadmap', 'report', 'answer', 'response', 'text',
+]);
+/** Minimal attribute-value sanitization: values here are controlled (ids,
+ *  statuses, counts), so collapse quotes rather than entity-escape. */
+function attrEsc(s) {
+    return String(s).replace(/"/g, "'").replace(/\n/g, ' ');
+}
+function scalarStr(v) {
+    if (v === null || v === undefined)
+        return '';
+    if (Array.isArray(v))
+        return v.map(scalarStr).join(', ');
+    if (typeof v === 'object')
+        return JSON.stringify(v);
+    return String(v);
+}
+function fencedJson(value) {
+    const json = JSON.stringify(value, null, 2);
+    let fence = '```';
+    while (json.includes(fence))
+        fence += '`';
+    return `${fence}json\n${json}\n${fence}`;
+}
+/** A string field is prose when it is named as such, spans lines, or is long
+ *  enough that it reads as a sentence rather than an identifier. */
+function isProse(name, v) {
+    if (typeof v !== 'string')
+        return false;
+    if (PROSE_FIELDS.has(name))
+        return true;
+    return v.includes('\n') || v.length > 80;
+}
+/** Keep a value safe inside a markdown table cell: pipes would split columns,
+ *  newlines would break the row. */
+function cellEsc(v) {
+    return scalarStr(v).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+/** An array renders as a count lead-in followed by the collection: a markdown
+ *  table when every element is an object, plain bullets otherwise. */
+function renderArray(name, arr) {
+    if (arr.length === 0)
+        return `0 ${name}.`;
+    const lead = `${arr.length} ${name}:`;
+    const allObjects = arr.every((x) => x !== null && typeof x === 'object' && !Array.isArray(x));
+    if (allObjects) {
+        const rows = arr;
+        const cols = [];
+        for (const r of rows)
+            for (const k of Object.keys(r))
+                if (!cols.includes(k))
+                    cols.push(k);
+        const head = `| ${cols.join(' | ')} |`;
+        const sep = `| ${cols.map(() => '---').join(' | ')} |`;
+        const body = rows.map((r) => `| ${cols.map((c) => cellEsc(r[c])).join(' | ')} |`).join('\n');
+        return `${lead}\n\n${head}\n${sep}\n${body}`;
+    }
+    const items = arr.map((x) => `- ${scalarStr(x)}`).join('\n');
+    return `${lead}\n${items}`;
+}
+/** Schema-driven fallback: turn a result object into agent-ready plain markdown.
+ *  Field order follows the leaf's declared output schema; any extra keys append
+ *  after. Scalars (and nested objects) list as `- name: value` bullets, prose
+ *  fields render as paragraphs, and arrays become a count lead-in plus a table
+ *  or bullets. No root tag — the result is read as a continuation of the prompt. */
+export function renderResult(result, help) {
+    const order = help.output.map((f) => f.name);
+    for (const k of Object.keys(result))
+        if (!order.includes(k))
+            order.push(k);
+    const bullets = [];
+    const proseFields = [];
+    const arrays = [];
+    for (const name of order) {
+        const v = result[name];
+        if (v === undefined || v === null)
+            continue;
+        if (Array.isArray(v)) {
+            arrays.push(renderArray(name, v));
+            continue;
+        }
+        if (isProse(name, v)) {
+            proseFields.push({ name, text: v });
+            continue;
+        }
+        // Scalars and nested objects alike list as a bullet (objects via compact JSON).
+        bullets.push(`- ${name}: ${scalarStr(v)}`);
+    }
+    const parts = [];
+    if (bullets.length > 0)
+        parts.push(bullets.join('\n'));
+    // Label prose only when more than one block would otherwise blur together.
+    const labelProse = proseFields.length > 1;
+    for (const { name, text } of proseFields) {
+        parts.push(labelProse ? `**${name}:** ${text}` : text);
+    }
+    for (const block of arrays)
+        parts.push(block);
+    return parts.join('\n\n');
+}
+/** Render a structured failure as an instruction-shaped block: what broke, what
+ *  was received, and the recovery road sign — the same recovery info the JSON
+ *  payload carries, shaped for the model to act on. */
+export function renderError(p) {
+    const lines = [p.message];
+    if (p.received !== undefined && p.received !== null && p.received !== '') {
+        lines.push(`received: ${scalarStr(p.received)}`);
+    }
+    if (p.field !== undefined)
+        lines.push(`field: ${p.field}`);
+    // Its own labeled line: a transport status is a fact about the call, not about
+    // the value the caller supplied.
+    if (p.http_status !== undefined)
+        lines.push(`http status: ${p.http_status}`);
+    if ('primaryCompleted' in p && p.primaryCompleted === true) {
+        lines.push('primaryCompleted: true');
+        lines.push(`Primary result (the command already completed):\n${fencedJson(p.result)}`);
+    }
+    lines.push(`Next: ${p.next}`);
+    return `<error code="${attrEsc(p.error)}">\n${lines.join('\n')}\n</error>`;
+}

package/dist/core/resolver.d.ts

@@ -0,0 +1,14 @@
+import type { InstalledMarketplace, InstalledPlugin, Scope } from '../types.js';
+export { listInstalledPluginsInRoot } from './installed-plugins.js';
+export declare function listInstalledPlugins(scope: Scope): InstalledPlugin[];
+export declare function listAllPlugins(): InstalledPlugin[];
+export declare function findPluginByName(name: string, scope?: Scope): InstalledPlugin | null;
+export interface ParsedSkillQualifier {
+    scope?: Scope;
+    segments: string[];
+}
+export declare function parseSkillQualifier(raw: string): ParsedSkillQualifier;
+export declare function listInstalledMarketplaces(scope: Exclude<Scope, 'builtin'>): InstalledMarketplace[];
+export declare function listAllMarketplaces(): InstalledMarketplace[];
+export declare function findMarketplaceByName(name: string, scope?: Exclude<Scope, 'builtin'>): InstalledMarketplace | null;
+export declare function scopeRootsLabel(): string;

package/dist/core/resolver.js

@@ -0,0 +1,111 @@
+import { join } from 'node:path';
+import { readConfig } from './config.js';
+import { listDirs, pathExists } from './fs-utils.js';
+import { readMarketplaceManifest } from './manifest.js';
+import { InputError } from './io.js';
+import { marketplacesDir, projectScopeRoot, scopeRoot, userScopeRoot, } from './scope.js';
+// Moved to installed-plugins.ts (a leaf module below config.ts) so
+// `readMergedLaunchConfig` can layer plugin-declared kinds without an import
+// cycle; re-exported here for this module's existing callers.
+export { listInstalledPluginsInRoot } from './installed-plugins.js';
+import { listInstalledPluginsInRoot } from './installed-plugins.js';
+export function listInstalledPlugins(scope) {
+    // The builtin scope has no scopeRoot, so this returns [] — builtin content is
+    // the shipped documents, not plugins.
+    const root = scopeRoot(scope);
+    if (!root)
+        return [];
+    return listInstalledPluginsInRoot(scope, root);
+}
+export function listAllPlugins() {
+    const scopes = [];
+    if (projectScopeRoot())
+        scopes.push('project');
+    scopes.push('user');
+    scopes.push('builtin');
+    return scopes.flatMap(listInstalledPlugins);
+}
+export function findPluginByName(name, scope) {
+    if (scope) {
+        return listInstalledPlugins(scope).find((p) => p.name === name) ?? null;
+    }
+    for (const s of ['project', 'user', 'builtin'].filter((sc) => sc === 'project' ? projectScopeRoot() !== null : true)) {
+        const match = listInstalledPlugins(s).find((p) => p.name === name);
+        if (match)
+            return match;
+    }
+    return null;
+}
+const SCOPE_QUALIFIERS = new Set(['user', 'project']);
+// Accepted identifier forms:
+//   <name>                         — bare name; scope-root first, then plugins
+//   <plugin>/<name>                — explicit plugin (plugin may contain slashes)
+//   <scope>/<name>                 — scope-root in a specific scope
+//   <scope>/<plugin>/<name>        — fully qualified
+export function parseSkillQualifier(raw) {
+    if (raw.includes(':')) {
+        const suggested = raw.replace(/:/g, '/');
+        throw new InputError({
+            error: 'invalid_qualifier',
+            message: "mixed separators ':' and '/' no longer supported; use slashes throughout",
+            received: raw,
+            field: 'name',
+            next: `Use ${suggested}.`,
+        });
+    }
+    const segments = raw.split('/');
+    if (SCOPE_QUALIFIERS.has(segments[0])) {
+        const scope = segments[0];
+        return { scope, segments: segments.slice(1) };
+    }
+    return { segments };
+}
+export function listInstalledMarketplaces(scope) {
+    const dir = marketplacesDir(scope);
+    if (!dir || !pathExists(dir))
+        return [];
+    const cfg = readConfig(scope);
+    const out = [];
+    for (const name of listDirs(dir)) {
+        const root = join(dir, name);
+        const manifest = readMarketplaceManifest(root);
+        if (!manifest)
+            continue;
+        const entry = cfg.marketplaces[name];
+        const url = entry && entry.url !== undefined ? entry.url : '';
+        const ref = entry && entry.ref !== undefined ? entry.ref : 'main';
+        out.push({
+            name,
+            scope,
+            root,
+            manifest,
+            url,
+            ref,
+        });
+    }
+    return out;
+}
+export function listAllMarketplaces() {
+    const scopes = [];
+    if (projectScopeRoot())
+        scopes.push('project');
+    scopes.push('user');
+    return scopes.flatMap(listInstalledMarketplaces);
+}
+export function findMarketplaceByName(name, scope) {
+    if (scope) {
+        return listInstalledMarketplaces(scope).find((m) => m.name === name) ?? null;
+    }
+    for (const s of ['project', 'user']) {
+        if (s === 'project' && !projectScopeRoot())
+            continue;
+        const found = listInstalledMarketplaces(s).find((m) => m.name === name);
+        if (found)
+            return found;
+    }
+    return null;
+}
+export function scopeRootsLabel() {
+    const proj = projectScopeRoot();
+    return proj ? `project=${proj}, user=${userScopeRoot()}` : `user=${userScopeRoot()}`;
+}

package/dist/core/runtime/branded-host.d.ts

@@ -0,0 +1,55 @@
+/** Machine-global host dir in this process owner’s HOME. Only the daemon reconciles it; agents do not install the branded host. Deliberately NOT under `CRTR_HOME` (tests override
+ *  that to an isolated temp): the branded binary is a per-machine artifact keyed
+ *  to the installed node, shared across every canvas home. */
+export declare function brandedHostDir(): string;
+export declare function brandedHostBin(): string;
+/** macOS keys FDA grants on the Mach-O cdhash. A real developer identity
+ *  keeps that hash stable across branded-host rebuilds; ad-hoc signing is the
+ *  portable default for machines without a local signing certificate. */
+export declare function codesignIdentitiesForBrandedHost(opts?: {
+    configured?: string | null;
+    discovered?: string | null;
+}): string[];
+export declare function signBrandedHostArtifacts(binPath: string, libnodePath: string | null, sign?: (path: string) => void): void;
+export declare function brandedHostWorks(binPath: string, timeoutMs?: number): boolean;
+/** Ensure the branded host binary exists and matches the live node; return its
+ *  absolute path. Idempotent and self-healing. Throws on a genuine build failure
+ *  (disk full / permissions); hostExecPath() turns that into a logged fallback to
+ *  a real node so a broken host never blocks launching. */
+export declare function ensureBrandedHost(opts?: {
+    execPath?: string;
+}): string;
+/** Find a working, ABI-compatible, non-branded `node` to rebuild from. Blocking:
+ *  for CLI / explicit reconcile only, never the daemon's event loop (use
+ *  findRealNodeAsync there). Returns null when none works. */
+export declare function findRealNode(): string | null;
+/** Non-blocking findRealNode for the daemon's event loop. */
+export declare function findRealNodeAsync(): Promise<string | null>;
+/** Forget remembered host health (tests). */
+export declare function resetBrandedHostHealthCache(): void;
+/** The node to exec for a short-lived helper child (forked worker, bash
+ *  supervisor, probe). Outside the branded host this is `process.execPath`
+ *  untouched. Inside it, a host that no longer starts (dyld cannot resolve a
+ *  moved Homebrew dependency) would abort every child, so a real node is used
+ *  instead. Never blocks: it returns the last known answer and refreshes it in
+ *  the background. A fork that still dies calls recheckChildNode() to learn the
+ *  truth at once. */
+export declare function childNodeExecPath(execPath?: string): string;
+/** Re-probe the host now (after a child died) and return the node to retry on;
+ *  equals `execPath` when the host is fine or no real node exists. */
+export declare function recheckChildNode(execPath?: string): Promise<string>;
+/** Like childNodeExecPath(), but first awaits a probe no older than `maxAgeMs`
+ *  (coalesced with any probe in flight). Use it right before a fork whose death
+ *  would lose work (a broker, a bash job, the inventory child) so a host broken
+ *  since the last probe is caught before the exec, not after. The probe is a
+ *  non-blocking `node -e ''`; outside the branded host this costs nothing. */
+export declare function freshChildNodeExecPath(execPath?: string, maxAgeMs?: number): Promise<string>;
+/** hostExecPath() for async launchers: inside the host it is verified fresh
+ *  rather than taken from the cache. */
+export declare function hostExecPathFresh(): Promise<string>;
+/** The path the engine (broker / daemon) should be launched from. On macOS in a
+ * compiled (production) build this is the validated branded host; otherwise —
+ * non-darwin (TCC is macOS-only), source/tsx (dev + the test suite: never copy
+ * 70 MB into the real ~/.crouter), or the explicit `CRTR_BRANDED_HOST=0`
+ * opt-out — it is the live node. */
+export declare function hostExecPath(): string;