@yagni-app/code-staging 1.2.4-staging.1803.1 → 1.2.4-staging.1821.1

package/dist/agentSources.d.ts

@@ -0,0 +1,78 @@
+/**
+ * A cloud run's skill sources (YAG-784): the mission file `sources.json` the
+ * backend writes beside `ticket.md`, and the compat options it turns into.
+ *
+ * The backend decides everything here: whether the working repo is trusted
+ * for agent runs (an admin's per-repo flag, standing in for pi's trust.json),
+ * and which org marketplace and personal skills snapshots it fetched and
+ * extracted under AGENT_SOURCES_ROOT. The CLI only reads the file, so it
+ * carries its own small validator rather than importing @yagni/shared (this
+ * package never takes a build-time dependency on a private workspace package).
+ * The contract is `AgentRunSourcesFile` in packages/shared/src/agentSources.ts.
+ *
+ * Everything is fail-soft: a missing, oversized, or garbled file means "no
+ * cloud sources" (the caller falls back to local behavior), and one bad
+ * source is dropped without touching the others.
+ */
+import type { CompatExtraRoot, CompatMarketplace } from "./claudeCompat.js";
+/** Where the backend extracts the org and personal snapshots in the sandbox. */
+export declare const AGENT_SOURCES_ROOT = "/opt/yagni/sources";
+export declare const AGENT_RUN_SOURCES_FILE_NAME = "sources.json";
+/** pi-harness.sh's default when YAGNI_MISSION_DIR is unset. */
+export declare const DEFAULT_MISSION_DIR = "/opt/yagni/mission";
+export interface AgentRunSources {
+    repo: {
+        fullName: string;
+        sha: string;
+        trusted: boolean;
+    };
+    org: {
+        fullName: string;
+        ref: string | null;
+        sha: string;
+        dir: string;
+        enabledPlugins: string[];
+    } | null;
+    personal: {
+        fullName: string;
+        ref: string | null;
+        sha: string;
+        dir: string;
+        userId: string;
+    } | null;
+}
+/** Validate a parsed sources.json (version 1). Null when it isn't one. */
+export declare function parseAgentRunSources(raw: unknown): AgentRunSources | null;
+/**
+ * Read `<missionDir>/sources.json`. Null when absent, too large, or invalid.
+ * Never throws. A file that is there but unusable is not the same as no file:
+ * the backend already recorded its sources as loaded, so `warn` says so (one
+ * stderr line in a headless run) rather than degrade to local mode silently.
+ */
+export declare function readAgentRunSources(missionDir: string, warn?: (line: string) => void): AgentRunSources | null;
+/** The mission dir the harness wrote into (`YAGNI_MISSION_DIR`, else its default). */
+export declare function missionDirFromEnv(env: NodeJS.ProcessEnv): string;
+/**
+ * `dir` as a realpath when it is absolute, an existing directory, and inside
+ * `sourcesRoot` after symlink resolution; else the reason it was refused.
+ */
+export declare function checkSourceDir(dir: string, sourcesRoot: string): {
+    dir: string;
+} | {
+    refused: string;
+};
+/** What a valid sources file asks `claudeCompatArgs` to load. */
+export interface CloudCompatOptions {
+    trustOverride: boolean;
+    extraRoots: CompatExtraRoot[];
+    marketplaces: CompatMarketplace[];
+    /** `label: reason` for each source dir that was refused. */
+    refused: string[];
+}
+/**
+ * Turn a sources file into compat options. Snapshot dirs must sit under
+ * `sourcesRoot` (AGENT_SOURCES_ROOT in the sandbox); any other dir is refused
+ * and reported, never loaded.
+ */
+export declare function cloudCompatOptions(sources: AgentRunSources, sourcesRoot?: string): CloudCompatOptions;
+//# sourceMappingURL=agentSources.d.ts.map

package/dist/agentSources.js

@@ -0,0 +1,194 @@
+/**
+ * A cloud run's skill sources (YAG-784): the mission file `sources.json` the
+ * backend writes beside `ticket.md`, and the compat options it turns into.
+ *
+ * The backend decides everything here: whether the working repo is trusted
+ * for agent runs (an admin's per-repo flag, standing in for pi's trust.json),
+ * and which org marketplace and personal skills snapshots it fetched and
+ * extracted under AGENT_SOURCES_ROOT. The CLI only reads the file, so it
+ * carries its own small validator rather than importing @yagni/shared (this
+ * package never takes a build-time dependency on a private workspace package).
+ * The contract is `AgentRunSourcesFile` in packages/shared/src/agentSources.ts.
+ *
+ * Everything is fail-soft: a missing, oversized, or garbled file means "no
+ * cloud sources" (the caller falls back to local behavior), and one bad
+ * source is dropped without touching the others.
+ */
+import { closeSync, fstatSync, openSync, readSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, sep } from "node:path";
+/** Where the backend extracts the org and personal snapshots in the sandbox. */
+export const AGENT_SOURCES_ROOT = "/opt/yagni/sources";
+export const AGENT_RUN_SOURCES_FILE_NAME = "sources.json";
+/** pi-harness.sh's default when YAGNI_MISSION_DIR is unset. */
+export const DEFAULT_MISSION_DIR = "/opt/yagni/mission";
+/** A sources file is a few hundred bytes; anything past this is not one. */
+const MAX_SOURCES_FILE_BYTES = 64 * 1024;
+/** Mirrors MAX_ENABLED_PLUGINS in the shared contract. */
+const MAX_ENABLED_PLUGINS = 50;
+/**
+ * A label, never a path. The owner allows `_` because a working repo can
+ * belong to an Enterprise Managed User (`jane_acme`); rejecting it would drop
+ * the whole file and silently ignore the repo's trust flag.
+ */
+const FULL_NAME = /^[A-Za-z0-9_-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
+const SHA = /^[0-9a-f]{40}$/;
+/** Same shape as claudePlugins' SAFE_SEGMENT: plugin names are path segments. */
+const PLUGIN_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function refOf(value) {
+    if (value === undefined || value === null)
+        return null;
+    return typeof value === "string" && value.length > 0 && value.length <= 255 ? value : undefined;
+}
+function snapshotBase(value) {
+    if (!isRecord(value))
+        return null;
+    const { fullName, sha, dir } = value;
+    const ref = refOf(value.ref);
+    if (typeof fullName !== "string" || !FULL_NAME.test(fullName))
+        return null;
+    if (typeof sha !== "string" || !SHA.test(sha))
+        return null;
+    if (typeof dir !== "string" || dir.length === 0)
+        return null;
+    if (ref === undefined)
+        return null;
+    return { fullName, ref, sha, dir };
+}
+/** Validate a parsed sources.json (version 1). Null when it isn't one. */
+export function parseAgentRunSources(raw) {
+    if (!isRecord(raw) || raw.version !== 1 || !isRecord(raw.repo))
+        return null;
+    const { fullName, sha, trusted } = raw.repo;
+    if (typeof fullName !== "string" || !FULL_NAME.test(fullName))
+        return null;
+    if (typeof sha !== "string" || !SHA.test(sha))
+        return null;
+    if (typeof trusted !== "boolean")
+        return null;
+    let org = null;
+    const orgBase = snapshotBase(raw.org);
+    if (orgBase && isRecord(raw.org) && Array.isArray(raw.org.enabledPlugins)) {
+        const enabledPlugins = [
+            ...new Set(raw.org.enabledPlugins.filter((p) => typeof p === "string" && PLUGIN_NAME.test(p))),
+        ].slice(0, MAX_ENABLED_PLUGINS);
+        org = { ...orgBase, enabledPlugins };
+    }
+    let personal = null;
+    const personalBase = snapshotBase(raw.personal);
+    if (personalBase && isRecord(raw.personal) && typeof raw.personal.userId === "string") {
+        personal = { ...personalBase, userId: raw.personal.userId };
+    }
+    return { repo: { fullName, sha, trusted }, org, personal };
+}
+/**
+ * Read `<missionDir>/sources.json`. Null when absent, too large, or invalid.
+ * Never throws. A file that is there but unusable is not the same as no file:
+ * the backend already recorded its sources as loaded, so `warn` says so (one
+ * stderr line in a headless run) rather than degrade to local mode silently.
+ */
+export function readAgentRunSources(missionDir, warn = () => { }) {
+    const path = join(missionDir, AGENT_RUN_SOURCES_FILE_NAME);
+    let fd = null;
+    try {
+        try {
+            fd = openSync(path, "r");
+        }
+        catch (err) {
+            if (err?.code === "ENOENT")
+                return null;
+            throw err;
+        }
+        const size = fstatSync(fd).size;
+        if (size === 0 || size > MAX_SOURCES_FILE_BYTES) {
+            warn(`Skills: ${path} ignored (${size === 0 ? "empty" : `larger than ${MAX_SOURCES_FILE_BYTES} bytes`}); no skills sources loaded`);
+            return null;
+        }
+        const buffer = Buffer.alloc(size);
+        readSync(fd, buffer, 0, size, 0);
+        const parsed = parseAgentRunSources(JSON.parse(buffer.toString("utf8")));
+        if (!parsed)
+            warn(`Skills: ${path} ignored (not a valid version 1 sources file); no skills sources loaded`);
+        return parsed;
+    }
+    catch (err) {
+        const why = err instanceof SyntaxError ? "not valid JSON" : err instanceof Error ? err.message : String(err);
+        warn(`Skills: ${path} ignored (${why}); no skills sources loaded`);
+        return null;
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // Already closed.
+            }
+        }
+    }
+}
+/** The mission dir the harness wrote into (`YAGNI_MISSION_DIR`, else its default). */
+export function missionDirFromEnv(env) {
+    const dir = env.YAGNI_MISSION_DIR?.trim();
+    return dir ? dir : DEFAULT_MISSION_DIR;
+}
+/**
+ * `dir` as a realpath when it is absolute, an existing directory, and inside
+ * `sourcesRoot` after symlink resolution; else the reason it was refused.
+ */
+export function checkSourceDir(dir, sourcesRoot) {
+    if (!isAbsolute(dir))
+        return { refused: "not an absolute path" };
+    let real;
+    let realRoot;
+    try {
+        real = realpathSync(dir);
+        realRoot = realpathSync(sourcesRoot);
+    }
+    catch {
+        return { refused: "not present in the sandbox" };
+    }
+    if (!real.startsWith(realRoot + sep))
+        return { refused: `outside ${sourcesRoot}` };
+    try {
+        if (!statSync(real).isDirectory())
+            return { refused: "not a directory" };
+    }
+    catch {
+        return { refused: "not present in the sandbox" };
+    }
+    return { dir: real };
+}
+/**
+ * Turn a sources file into compat options. Snapshot dirs must sit under
+ * `sourcesRoot` (AGENT_SOURCES_ROOT in the sandbox); any other dir is refused
+ * and reported, never loaded.
+ */
+export function cloudCompatOptions(sources, sourcesRoot = AGENT_SOURCES_ROOT) {
+    const out = {
+        trustOverride: sources.repo.trusted,
+        extraRoots: [],
+        marketplaces: [],
+        refused: [],
+    };
+    if (sources.org) {
+        const label = `${sources.org.fullName} @ ${sources.org.sha.slice(0, 7)}`;
+        const checked = checkSourceDir(sources.org.dir, sourcesRoot);
+        if ("dir" in checked)
+            out.marketplaces.push({ root: checked.dir, enabled: sources.org.enabledPlugins, label });
+        else
+            out.refused.push(`${label}: ${checked.refused}`);
+    }
+    if (sources.personal) {
+        const label = `${sources.personal.fullName} @ ${sources.personal.sha.slice(0, 7)}`;
+        const checked = checkSourceDir(sources.personal.dir, sourcesRoot);
+        if ("dir" in checked)
+            out.extraRoots.push({ root: checked.dir, label });
+        else
+            out.refused.push(`${label}: ${checked.refused}`);
+    }
+    return out;
+}
+//# sourceMappingURL=agentSources.js.map

package/dist/claudeCompat.d.ts

@@ -107,6 +107,60 @@ export declare function readTrustDecision(agentDir: string, cwd: string): boolea
  * asked again next launch.
  */
 export declare function writeTrustDecision(agentDir: string, cwd: string, decision: boolean): void;
+/**
+ * A personal skills root (a person's own skills repository, extracted into the
+ * sandbox). Any of the layouts in EXTRA_ROOT_LAYOUT that exist load,
+ * regardless of the working repo's trust: the backend only hands over a root
+ * it authorized.
+ */
+export interface CompatExtraRoot {
+    root: string;
+    /** Human label for logs, e.g. `jane/skills`. */
+    label: string;
+}
+/**
+ * A plugin marketplace checkout (`<root>/.claude-plugin/marketplace.json`) of
+ * which only the `enabled` plugins load. Only relative-path plugin sources are
+ * supported; object sources (github, url, npm) are reported, never fetched.
+ */
+export interface CompatMarketplace {
+    root: string;
+    enabled: string[];
+    label: string;
+}
+/** Personal root layouts, in load order. */
+export declare const EXTRA_ROOT_LAYOUT: {
+    readonly skills: readonly ["skills", ".claude/skills", ".agents/skills"];
+    readonly commands: readonly ["commands", ".claude/commands"];
+    readonly rules: readonly ["rules", ".claude/rules"];
+};
+/** Bound on the symlink scan of one asset path, so a huge tree can't stall a launch. */
+export declare const SYMLINK_SCAN_LIMIT = 20000;
+/**
+ * `<root>/<rel>` as a realpath when it exists, is a directory, stays inside
+ * `root` after symlink resolution, and holds no symlink pointing outside it.
+ * Every source the interactive launcher never read goes through this, so a
+ * hostile link in a repo or snapshot can't hand pi a directory outside it.
+ * `scanLimit` exists for tests: a tree with more entries than it is refused.
+ */
+export declare function safeSourceDir(root: string, rel: string, scanLimit?: number): string | null;
+/** One source's contribution, summarized for the launcher's log line. */
+export interface CompatSourceSummary {
+    label: string;
+    kind: "user" | "project" | "personal" | "org-marketplace";
+    skills: string[];
+    commands: string[];
+    rulesDirs: string[];
+    /** `name@marketplace` keys of the plugins it contributed. */
+    plugins: string[];
+    /** Things present but not loaded (unsupported plugin parts, missing plugins). */
+    unsupported: string[];
+}
+/** The enabled plugins of one marketplace checkout, plus what could not load. Never throws. */
+export declare function marketplacePlugins(mp: CompatMarketplace): {
+    plugins: PluginAssets[];
+    unsupported: string[];
+};
 export interface ClaudeCompatDeps {
     cwd: string;
     /** The hermetic pi agent dir for the active profile (holds trust.json). */
@@ -116,6 +170,26 @@ export interface ClaudeCompatDeps {
     interactive?: boolean;
     /** The one-time trust question; injectable for tests. */
     confirm?: (question: string) => Promise<boolean>;
+    /**
+     * A trust decision made elsewhere (a cloud run's per-repo admin flag). It
+     * replaces the trust.json lookup and the prompt, and is never written back.
+     */
+    trustOverride?: boolean;
+    /** False skips `~/.claude`, home plugins and the YAGNI ledger. Default true. */
+    userScope?: boolean;
+    /** False never emits YAGNI_CLAUDE_PLUGIN_MCP (headless runs). Default true. */
+    pluginMcp?: boolean;
+    /**
+     * Once the folder is trusted, also wire `<cwd>/.agents/skills`, `.pi/skills`
+     * (`--skill`) and `.pi/prompts` (`--prompt-template`) explicitly, so a
+     * headless run never needs pi's `--approve` (which would also run the repo's
+     * `.pi/extensions` code). Default false.
+     */
+    projectNativeSkills?: boolean;
+    /** Personal skills roots; load regardless of the folder's trust. */
+    extraRoots?: CompatExtraRoot[];
+    /** Plugin marketplaces with an explicit enabled list; load regardless of trust. */
+    marketplaces?: CompatMarketplace[];
 }
 export declare function compatDisabled(env: NodeJS.ProcessEnv): boolean;
 export interface ClaudeCompatLaunch {
@@ -123,12 +197,21 @@ export interface ClaudeCompatLaunch {
     argv: string[];
     /** Extra child env (plugin agent dirs, rules dirs) for the extension. */
     env: Record<string, string>;
+    /**
+     * What each source contributed, for logging. Absent when nothing loaded and
+     * no extra source was asked for.
+     */
+    sources?: CompatSourceSummary[];
 }
 /**
  * The extra pi argv + child env for this launch: user-scope dirs and plugins
  * unconditionally, project-sourced dirs/plugins/rules once trusted, asking
  * (and persisting) the trust decision when needed. Everything is fail-soft —
  * compat can only add flags/env, never break a launch.
+ *
+ * The optional deps (`trustOverride`, `userScope`, `pluginMcp`,
+ * `projectNativeSkills`, `extraRoots`, `marketplaces`) serve headless cloud
+ * runs; left unset, the argv and env are exactly the interactive behavior.
  */
 export declare function claudeCompatArgs(deps: ClaudeCompatDeps): Promise<ClaudeCompatLaunch>;
 /** One plugin as the in-session `/plugin` panel sees it. */