@phnx-labs/agents-cli 1.22.84 → 1.22.86

package/dist/lib/workflows-registry.js

@@ -0,0 +1,280 @@
+/**
+ * Workflow target registry — the ONE place that says how each
+ * workflows-capable harness stores a synced workflow on disk.
+ *
+ * `WORKFLOW_TARGETS` is the declarative shape (container dir, file layout,
+ * transform, ownership marker); the engine below (`listWorkflowsForAgent`,
+ * `syncWorkflowToVersion`, `removeWorkflowFromVersion`,
+ * `workflowContentMatches`) and the staleness detector are generic over it, so
+ * adding a harness is one entry here plus its `workflows` capability flag in
+ * `agent-spec/agents.ts` — never another `if (agent === '...')` arm in the
+ * writer, the lister, the remover, the doctor drift check, and the detector.
+ * A completeness test pins `Object.keys(WORKFLOW_TARGETS)` to
+ * `capableAgents('workflows')` so the flag and the shape cannot drift.
+ *
+ * Same pattern as `SUBAGENT_TARGETS` in `subagents-registry.ts`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getVersionHomePath } from './installations/versions.js';
+import { dirsContentMatch, normalizeResourceContent } from './resource-content-diff.js';
+import { antigravityWorkflowMarker, antigravityWorkflowsDir, grokWorkflowMarker, kimiWorkflowMarker, openclawWorkflowMarker, parseWorkflowFrontmatter, renderGooseRecipeYaml, selectedWorkflowSubagents, transformWorkflowForAntigravity, transformWorkflowForGrok, transformWorkflowForKimi, transformWorkflowForOpenClaw, writeGooseSubrecipe, } from './workflows.js';
+function readdirSafe(dir) {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+function renderedMatches(homePath, expected) {
+    let actual;
+    try {
+        actual = fs.readFileSync(homePath, 'utf-8');
+    }
+    catch {
+        return false;
+    }
+    return normalizeResourceContent(actual) === normalizeResourceContent(expected);
+}
+// ── layouts ──────────────────────────────────────────────────────────────────
+/**
+ * One rendered `<name><ext>` file per workflow, owned via a marker the
+ * transform embeds (antigravity, openclaw, grok).
+ */
+function renderedFile(opts) {
+    const file = (dir, name) => path.join(dir, `${name}${opts.ext}`);
+    return {
+        label: opts.label,
+        dir: opts.dir,
+        names(dir) {
+            return readdirSafe(dir)
+                .filter((d) => d.isFile() && d.name.endsWith(opts.ext) && !d.name.startsWith('.'))
+                .map((d) => d.name.slice(0, -opts.ext.length))
+                .filter((base) => opts.marker(file(dir, base)) === base);
+        },
+        write(dir, wf) {
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(file(dir, wf.name), opts.transform(wf.path, wf.name), 'utf-8');
+        },
+        occupied(dir, name) {
+            const target = file(dir, name);
+            return fs.existsSync(target) ? [target] : [];
+        },
+        managed(dir, name) {
+            const target = file(dir, name);
+            if (!fs.existsSync(target))
+                return null;
+            return opts.marker(target) === name;
+        },
+        matches(dir, wf) {
+            return renderedMatches(file(dir, wf.name), opts.transform(wf.path, wf.name));
+        },
+    };
+}
+/**
+ * Kimi flow skill: a `<name>/SKILL.md` directory whose frontmatter carries
+ * `type: flow` and the `agents_workflow` marker.
+ */
+const kimiFlowSkill = {
+    label: 'Kimi skill',
+    dir: (versionHome) => path.join(versionHome, '.kimi-code', 'skills'),
+    names(dir) {
+        return readdirSafe(dir)
+            .filter((d) => d.isDirectory() && fs.existsSync(path.join(dir, d.name, 'SKILL.md')))
+            .filter((d) => kimiWorkflowMarker(path.join(dir, d.name, 'SKILL.md')) === d.name)
+            .map((d) => d.name);
+    },
+    write(dir, wf) {
+        const skillDir = path.join(dir, wf.name);
+        fs.mkdirSync(skillDir, { recursive: true });
+        fs.writeFileSync(path.join(skillDir, 'SKILL.md'), transformWorkflowForKimi(wf.path, wf.name), 'utf-8');
+    },
+    occupied(dir, name) {
+        const skillDir = path.join(dir, name);
+        return fs.existsSync(skillDir) ? [skillDir] : [];
+    },
+    managed(dir, name) {
+        const skillDir = path.join(dir, name);
+        if (!fs.existsSync(skillDir))
+            return null;
+        return kimiWorkflowMarker(path.join(skillDir, 'SKILL.md')) === name;
+    },
+    matches(dir, wf) {
+        return renderedMatches(path.join(dir, wf.name, 'SKILL.md'), transformWorkflowForKimi(wf.path, wf.name));
+    },
+};
+/**
+ * Goose recipe: `<name>.yaml` plus a `<name>.subrecipes/` dir holding one YAML
+ * per selected workflow subagent. Goose has no ownership marker, so presence
+ * is ownership.
+ */
+const gooseRecipe = {
+    label: 'Goose recipe',
+    dir: (versionHome) => path.join(versionHome, '.config', 'goose', 'recipes'),
+    names(dir) {
+        return readdirSafe(dir)
+            .filter((d) => d.isFile() && d.name.endsWith('.yaml') && !d.name.startsWith('.'))
+            .map((d) => d.name.slice(0, -'.yaml'.length));
+    },
+    write(dir, wf) {
+        const frontmatter = parseWorkflowFrontmatter(wf.path);
+        const recipeYaml = frontmatter ? renderGooseRecipeYaml(wf.path, wf.name) : null;
+        if (!frontmatter || recipeYaml == null) {
+            throw new Error(`Workflow '${wf.name}' has invalid WORKFLOW.md frontmatter`);
+        }
+        const subrecipesDir = path.join(dir, `${wf.name}.subrecipes`);
+        fs.mkdirSync(dir, { recursive: true });
+        if (fs.existsSync(subrecipesDir)) {
+            fs.rmSync(subrecipesDir, { recursive: true, force: true });
+        }
+        for (const subagentName of selectedWorkflowSubagents(wf.path, frontmatter.allowedAgents)) {
+            writeGooseSubrecipe(wf.path, subagentName, subrecipesDir);
+        }
+        fs.writeFileSync(path.join(dir, `${wf.name}.yaml`), recipeYaml, 'utf-8');
+    },
+    occupied(dir, name) {
+        return [path.join(dir, `${name}.yaml`), path.join(dir, `${name}.subrecipes`)].filter((p) => fs.existsSync(p));
+    },
+    managed(dir, name) {
+        return gooseRecipe.occupied(dir, name).length > 0 ? true : null;
+    },
+    matches(dir, wf) {
+        const expected = renderGooseRecipeYaml(wf.path, wf.name);
+        if (expected == null)
+            return false;
+        return renderedMatches(path.join(dir, `${wf.name}.yaml`), expected);
+    },
+};
+/**
+ * The canonical bundle copied verbatim: `<name>/WORKFLOW.md` (plus its
+ * subagents/ tree) under `{versionHome}/workflows/`. No marker — the dir is
+ * agents-cli's by construction.
+ */
+const workflowBundle = {
+    label: 'Workflow',
+    dir: (versionHome) => path.join(versionHome, 'workflows'),
+    names(dir) {
+        return readdirSafe(dir)
+            .filter((d) => d.isDirectory() && fs.existsSync(path.join(dir, d.name, 'WORKFLOW.md')))
+            .map((d) => d.name);
+    },
+    write(dir, wf) {
+        const target = path.join(dir, wf.name);
+        fs.mkdirSync(dir, { recursive: true });
+        if (fs.existsSync(target)) {
+            fs.rmSync(target, { recursive: true, force: true });
+        }
+        fs.cpSync(wf.path, target, { recursive: true });
+    },
+    occupied(dir, name) {
+        const target = path.join(dir, name);
+        return fs.existsSync(target) ? [target] : [];
+    },
+    managed(dir, name) {
+        return fs.existsSync(path.join(dir, name)) ? true : null;
+    },
+    matches(dir, wf) {
+        return dirsContentMatch(wf.path, path.join(dir, wf.name));
+    },
+};
+// ── the registry ─────────────────────────────────────────────────────────────
+/**
+ * Single source of truth for how each workflows-capable harness stores
+ * workflows. The keys MUST match `capableAgents('workflows')` (the `workflows`
+ * flag in `agent-spec/agents.ts`): the capability flag is the version gate,
+ * this table is the shape.
+ */
+export const WORKFLOW_TARGETS = {
+    claude: workflowBundle,
+    kimi: kimiFlowSkill,
+    goose: gooseRecipe,
+    // Antigravity discovers workflows in the shared HOME-global dir `agy` scans
+    // at startup, never in a version home — see `antigravityWorkflowsDir`.
+    antigravity: renderedFile({
+        label: 'Antigravity workflow',
+        dir: () => antigravityWorkflowsDir(),
+        ext: '.md',
+        transform: transformWorkflowForAntigravity,
+        marker: antigravityWorkflowMarker,
+    }),
+    openclaw: renderedFile({
+        label: 'OpenClaw workflow',
+        dir: (versionHome) => path.join(versionHome, '.openclaw', 'workflows'),
+        ext: '.lobster',
+        transform: transformWorkflowForOpenClaw,
+        marker: openclawWorkflowMarker,
+    }),
+    grok: renderedFile({
+        label: 'Grok workflow',
+        dir: (versionHome) => path.join(versionHome, '.grok', 'workflows'),
+        ext: '.rhai',
+        transform: transformWorkflowForGrok,
+        marker: grokWorkflowMarker,
+    }),
+};
+/** The registered target for `agent`; throws for a harness that has none. */
+export function workflowTarget(agent) {
+    const target = WORKFLOW_TARGETS[agent];
+    if (!target) {
+        throw new Error(`${agent} has no workflow target (not in capableAgents('workflows'))`);
+    }
+    return target;
+}
+// ── the generic engine ───────────────────────────────────────────────────────
+/** Workflow names agents-cli has synced into `versionHome` for `agent`. */
+export function listWorkflowsForAgent(agent, versionHome) {
+    const target = workflowTarget(agent);
+    return target.names(target.dir(versionHome));
+}
+/**
+ * Materialize the central bundle at `workflowPath` as `name` in `agent`'s
+ * `versionHome`, in that harness's native layout. Refuses to clobber a
+ * user-authored file of the same name (the ownership marker is the tell) and
+ * is idempotent over an agents-cli-managed one.
+ */
+export function syncWorkflowToVersion(workflowPath, name, agent, versionHome) {
+    const target = workflowTarget(agent);
+    const dir = target.dir(versionHome);
+    try {
+        if (target.managed(dir, name) === false) {
+            return { success: false, error: `${target.label} '${name}' already exists and is not managed by agents-cli` };
+        }
+        target.write(dir, { name, path: workflowPath });
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}
+/** Remove workflow `name` from `agent@version`; refuses a user-authored file. */
+export function removeWorkflowFromVersion(agent, version, name) {
+    const target = workflowTarget(agent);
+    const dir = target.dir(getVersionHomePath(agent, version));
+    const occupied = target.occupied(dir, name);
+    if (occupied.length === 0) {
+        return { success: false, error: `Workflow '${name}' not synced to ${agent}@${version}` };
+    }
+    if (target.managed(dir, name) === false) {
+        return { success: false, error: `${target.label} '${name}' is not managed by agents-cli` };
+    }
+    try {
+        for (const entry of occupied) {
+            fs.rmSync(entry, { recursive: true, force: true });
+        }
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}
+/**
+ * True when workflow `name` materialized in `agent`'s `versionHome` byte-matches
+ * what the writer would produce NOW from `sourcePath` — the content-drift
+ * predicate `agents doctor` uses. Returns false when the home copy is absent
+ * (surfaced as `missing` at the name level, not here).
+ */
+export function workflowContentMatches(agent, versionHome, name, sourcePath) {
+    const target = workflowTarget(agent);
+    return target.matches(target.dir(versionHome), { name, path: sourcePath });
+}

package/dist/lib/workflows.d.ts

@@ -373,29 +373,29 @@ export declare function removeWorkflow(name: string): {
     success: boolean;
     error?: string;
 };
-/** List workflow names synced into a specific agent version home. */
-export declare function listWorkflowsForAgent(agent: AgentId, versionHome: string): string[];
 /**
- * True when workflow `name` materialized in `agent`'s version home byte-matches
- * what the writer would produce NOW from `sourcePath` — the content-drift
- * predicate `agents doctor` uses. Layout-aware per the same per-harness map the
- * writer (`syncWorkflowToVersion`) and detector use: Claude/default copy the
- * whole WORKFLOW.md tree (recursive dir compare); Kimi/Antigravity/OpenClaw/Grok
- * render one transformed file; Goose renders a recipe YAML. Antigravity's target
- * is the shared HOME-global dir, not a per-version path. Returns false when the
- * home copy is absent (surfaced as `missing` at the name level, not here).
+ * Antigravity user workflows are NOT version-isolated. `agy` scans a single,
+ * shared, HOME-global directory at startup — `~/.gemini/config/global_workflows/`
+ * — and that dir is a real directory in the user's home, never symlinked into a
+ * per-version home (only `~/.gemini/antigravity-cli` is version-scoped). Writing
+ * into a version home therefore lands somewhere agy never reads. So every
+ * antigravity version resolves to the same real shared dir; `versionHome` is
+ * intentionally ignored. (Verified via strace of `agy`: it opens
+ * `$HOME/.gemini/config/global_workflows/<name>.md` and never the version home.)
  */
-export declare function workflowContentMatches(agent: AgentId, versionHome: string, name: string, sourcePath: string): boolean;
-/** Copy a workflow directory into a version home at {versionHome}/workflows/<name>/. */
-export declare function syncWorkflowToVersion(workflowPath: string, name: string, agent: AgentId, versionHome: string): {
-    success: boolean;
-    error?: string;
-};
-/** Remove a workflow from a specific agent version home. */
-export declare function removeWorkflowFromVersion(agent: AgentId, version: string, name: string): {
-    success: boolean;
-    error?: string;
-};
+export declare function antigravityWorkflowsDir(): string;
+export declare function selectedWorkflowSubagents(workflowPath: string, allowedAgents?: string[]): string[];
+export declare function writeGooseSubrecipe(workflowPath: string, subrecipeName: string, destDir: string): void;
+/**
+ * Render the main Goose recipe YAML for a workflow — the exact bytes the Goose
+ * `WORKFLOW_TARGETS` entry writes to `<name>.yaml`. Extracted so the writer and
+ * the doctor content-drift check (`matches`) render from ONE source and can
+ * never disagree. Returns null on invalid frontmatter.
+ */
+export declare function renderGooseRecipeYaml(workflowPath: string, name: string): string | null;
+export declare function kimiWorkflowMarker(filePath: string): string | null;
+export declare function antigravityWorkflowMarker(filePath: string): string | null;
+export declare function openclawWorkflowMarker(filePath: string): string | null;
 /** Iterate all installed (agent, version) pairs that support workflows. */
 export declare function iterWorkflowsCapableVersions(filter?: {
     agent?: AgentId;