@agent-native/core 0.51.6 → 0.51.8

package/dist/cli/skills.js

@@ -21,7 +21,7 @@ Usage:
   npx @agent-native/core@latest skills list
   npx @agent-native/core@latest skills status [assets|design-exploration|visual-plan|visual-recap|context-xray] [--client codex|claude-code|all] [--scope user|project] [--json]
   npx @agent-native/core@latest skills update [assets|design-exploration|visual-plan|visual-recap|context-xray] [--client codex|claude-code|all] [--scope user|project] [--dry-run] [--json]
-  npx @agent-native/core@latest skills add assets|design-exploration|visual-plan|visual-recap|context-xray [--client codex|claude-code|claude-code-cli|cowork|all] [--scope user|project] [--mcp-url <url>] [--no-connect] [--with-github-action] [--yes] [--dry-run] [--json]
+  npx @agent-native/core@latest skills add assets|design-exploration|visual-plan|visual-recap|context-xray [--client codex|claude-code|claude-code-cli|cowork|all] [--scope user|project] [--mode hosted|local-files|self-hosted] [--mcp-url <url>] [--no-connect] [--with-github-action] [--yes] [--dry-run] [--json]
   npx @agent-native/core@latest skills add <manifest-or-app-dir|skill-repo> [--skill <name>] [--client ...] [--yes]
 
 Examples:
@@ -30,6 +30,8 @@ Examples:
   npx @agent-native/core@latest skills add visual-plan
   npx @agent-native/core@latest skills add visual-recap
   npx @agent-native/core@latest skills add visual-recap --with-github-action
+  npx @agent-native/core@latest skills add visual-plan --mode local-files
+  npx @agent-native/core@latest skills add visual-plan --mode self-hosted --mcp-url https://my-plan-app.example.com
   npx @agent-native/core@latest skills status visual-plan
   npx @agent-native/core@latest skills update visual-plan
   npx @agent-native/core@latest skills add visual-plan --no-connect
@@ -59,6 +61,12 @@ deployment) instead of the built-in hosted default — a bare origin gets the
 standard /_agent-native/mcp path appended. Use app-skill pack for marketplace
 bundles and custom adapter output.
 
+When installing visual-plan or visual-recap interactively, the CLI asks where
+plans and recaps should live: hosted Plans for shareable links/comments, local
+files for "No sharing, all local.", or a self-hosted/custom Plan app URL.
+Pass --mode to choose directly. Local-files mode skips MCP registration and
+auth and installs instructions that default to MDX folders plus local preview.
+
 When installing visual-recap interactively, the CLI offers to add the optional PR
 Visual Recap GitHub Action. Pass --with-github-action to write it directly, then
 run "npx @agent-native/core@latest recap setup" / "npx @agent-native/core@latest recap doctor" to configure and
@@ -2244,12 +2252,60 @@ function stableSkillHash(files) {
     }
     return hash.digest("hex").slice(0, 16);
 }
-function skillFilesForBuiltIn(appSkillId) {
+function insertAfterFrontmatter(markdown, block) {
+    if (!block.trim())
+        return markdown;
+    const match = markdown.match(/^---\n[\s\S]*?\n---\n/);
+    if (!match)
+        return `${block}\n\n${markdown}`;
+    return `${match[0]}\n${block.trim()}\n\n${markdown.slice(match[0].length)}`;
+}
+function planModeInstructionBlock(input) {
+    if (input.mode === "local-files") {
+        return `## Installed Mode
+
+Default storage for this installation: local files. Create and update plans and
+recaps as MDX folders under \`plans/<slug>/\`, run
+\`npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind plan|recap\`,
+and report the local preview URL or path. No sharing, all local. Use a hosted
+or self-hosted Plan MCP connector only if the user explicitly asks to publish or
+share.`;
+    }
+    if (input.mode === "self-hosted") {
+        return `## Installed Mode
+
+Default storage for this installation: the configured self-hosted/custom Plan
+app${input.mcpUrl ? ` at \`${input.mcpUrl}\`` : ""}. Use that Plan MCP connector
+for plans and recaps instead of assuming \`https://plan.agent-native.com\`.`;
+    }
+    return "";
+}
+function applyPlanModeToSkillMarkdown(markdown, input) {
+    if (input.appSkillId !== "visual-plans")
+        return markdown;
+    const block = planModeInstructionBlock({
+        mode: input.mode,
+        mcpUrl: input.mcpUrl,
+    });
+    return insertAfterFrontmatter(markdown, block);
+}
+function skillFilesForBuiltIn(appSkillId, options = {}) {
     const entry = BUILT_IN_APP_SKILLS[appSkillId];
     const skills = {
-        [entry.skillName]: entry.skillMarkdown,
+        [entry.skillName]: applyPlanModeToSkillMarkdown(entry.skillMarkdown, {
+            appSkillId,
+            mode: options.planMode,
+            mcpUrl: options.mcpUrl,
+        }),
         ...builtInExtraSkills(entry),
     };
+    for (const [skillName, skillMarkdown] of Object.entries(builtInExtraSkills(entry))) {
+        skills[skillName] = applyPlanModeToSkillMarkdown(skillMarkdown, {
+            appSkillId,
+            mode: options.planMode,
+            mcpUrl: options.mcpUrl,
+        });
+    }
     const extraFiles = builtInExtraFiles(entry);
     const out = {};
     for (const [skillName, skillMarkdown] of Object.entries(skills)) {
@@ -2261,11 +2317,12 @@ function skillFilesForBuiltIn(appSkillId) {
             appSkillId,
             displayName: entry.manifest.displayName,
             skillName,
-            mcpUrl: isLocalOnlyBuiltInSkill(entry)
+            mcpUrl: isLocalOnlyBuiltInSkill(entry) || options.planMode === "local-files"
                 ? ""
-                : entry.manifest.hosted.mcpUrl,
+                : (options.mcpUrl ?? entry.manifest.hosted.mcpUrl),
             files,
             contentHash: stableSkillHash(files),
+            planMode: options.planMode,
         };
     }
     return out;
@@ -2295,6 +2352,7 @@ function writeSkillFolder(dir, bundle, installedAt = new Date().toISOString()) {
         mcpUrl: bundle.mcpUrl,
         installedAt,
         updateCommand: `npx @agent-native/core@latest skills update ${bundle.skillName}`,
+        ...(bundle.planMode ? { planMode: bundle.planMode } : {}),
     };
     fs.writeFileSync(path.join(dir, AGENT_NATIVE_SKILL_METADATA_FILE), `${JSON.stringify(metadata, null, 2)}\n`, "utf-8");
 }
@@ -2324,7 +2382,10 @@ function builtInSkillsRootForAgent(agent, scope, baseDir) {
  * (which would have to be published to npm first). Returns the written folders.
  */
 function installBuiltInInstructions(input) {
-    const bundles = Object.values(skillFilesForBuiltIn(input.appSkillId)).filter((bundle) => !input.onlySkillNames || input.onlySkillNames.includes(bundle.skillName));
+    const bundles = Object.values(skillFilesForBuiltIn(input.appSkillId, {
+        planMode: input.planMode,
+        mcpUrl: input.mcpUrl,
+    })).filter((bundle) => !input.onlySkillNames || input.onlySkillNames.includes(bundle.skillName));
     const written = [];
     for (const agent of input.skillsAgents) {
         const root = builtInSkillsRootForAgent(agent, input.scope, input.baseDir);
@@ -2438,7 +2499,7 @@ function clientFilterForStatus(parsed) {
 }
 function collectSkillInstallStates(parsed, options) {
     const appSkillIds = targetIdsForStatus(parsed);
-    const latest = latestSkillBundlesForTargets(appSkillIds);
+    const defaultLatest = latestSkillBundlesForTargets(appSkillIds);
     const roots = skillSearchRoots({
         baseDir: options.baseDir ?? process.cwd(),
         clients: clientFilterForStatus(parsed),
@@ -2447,7 +2508,7 @@ function collectSkillInstallStates(parsed, options) {
     const states = [];
     const seenDirs = new Set();
     for (const root of roots) {
-        for (const bundle of Object.values(latest)) {
+        for (const bundle of Object.values(defaultLatest)) {
             const dir = path.join(root.root, bundle.skillName);
             const resolvedDir = path.resolve(dir);
             if (seenDirs.has(resolvedDir) || !fs.existsSync(dir))
@@ -2456,35 +2517,41 @@ function collectSkillInstallStates(parsed, options) {
                 continue;
             seenDirs.add(resolvedDir);
             const files = listSkillFolderFiles(dir);
-            const installedHash = Object.keys(files).length > 0 ? stableSkillHash(files) : null;
             const metadata = readSkillInstallMetadata(dir);
+            const stateBundle = skillFilesForBuiltIn(bundle.appSkillId, {
+                planMode: metadata?.planMode,
+                mcpUrl: metadata?.mcpUrl,
+            })[bundle.skillName] ?? bundle;
+            const installedHash = Object.keys(files).length > 0 ? stableSkillHash(files) : null;
             states.push({
-                appSkillId: bundle.appSkillId,
-                displayName: bundle.displayName,
-                skillName: bundle.skillName,
+                appSkillId: stateBundle.appSkillId,
+                displayName: stateBundle.displayName,
+                skillName: stateBundle.skillName,
                 path: dir,
                 root: root.root,
                 scope: root.scope,
                 client: root.client,
-                latestHash: bundle.contentHash,
+                latestHash: stateBundle.contentHash,
                 installedHash,
                 metadataHash: metadata?.contentHash,
-                current: installedHash === bundle.contentHash,
+                current: installedHash === stateBundle.contentHash,
                 managed: metadata?.source === "agent-native",
+                planMode: metadata?.planMode,
+                mcpUrl: metadata?.mcpUrl,
             });
         }
     }
     return states.sort((a, b) => `${a.skillName}:${a.path}`.localeCompare(`${b.skillName}:${b.path}`));
 }
 function updateSkillInstallStates(states, dryRun) {
-    const latest = latestSkillBundlesForTargets([
-        ...new Set(states.map((state) => state.appSkillId)),
-    ]);
     const updated = [];
     for (const state of states) {
         if (state.current && state.managed)
             continue;
-        const bundle = latest[state.skillName];
+        const bundle = skillFilesForBuiltIn(state.appSkillId, {
+            planMode: state.planMode,
+            mcpUrl: state.mcpUrl,
+        })[state.skillName];
         if (!bundle)
             continue;
         if (!dryRun)
@@ -2622,6 +2689,56 @@ async function promptForScope(context) {
     }
     return result === "project" ? "project" : "user";
 }
+async function promptForPlanMode(context) {
+    const clack = await import("@clack/prompts");
+    const result = await clack.select({
+        message: "Where should visual plans and recaps live?",
+        options: [
+            {
+                value: "hosted",
+                label: "Hosted Plans, shareable links",
+                hint: "Stores plans at plan.agent-native.com. Enables sharing, comments, browser editor. Requires one-time browser sign-in.",
+            },
+            {
+                value: "local-files",
+                label: "Local files only",
+                hint: "Writes plans/<name>/plan.mdx in this repo and opens a local preview. No sharing, all local.",
+            },
+            {
+                value: "self-hosted",
+                label: "Self-hosted/custom URL",
+                hint: "Connect to your own Plan app or local dev tunnel.",
+            },
+        ],
+        initialValue: context.initialMode,
+    });
+    if (clack.isCancel(result)) {
+        clack.cancel("Cancelled.");
+        return null;
+    }
+    return normalizePlanInstallMode(String(result));
+}
+async function promptForPlanMcpUrl() {
+    const clack = await import("@clack/prompts");
+    const result = await clack.text({
+        message: "Plan app URL or MCP URL",
+        placeholder: "https://my-plan-app.example.com",
+        validate(value) {
+            try {
+                resolveMcpUrlOverride(value);
+                return undefined;
+            }
+            catch (err) {
+                return err?.message ?? "Enter a valid http:// or https:// URL.";
+            }
+        },
+    });
+    if (clack.isCancel(result)) {
+        clack.cancel("Cancelled.");
+        return null;
+    }
+    return String(result).trim();
+}
 async function promptForSkills(context) {
     const clack = await import("@clack/prompts");
     const result = await clack.multiselect({
@@ -2659,6 +2776,30 @@ async function resolveSkillsClients(parsed, options) {
     }
     return selected;
 }
+function normalizePlanInstallMode(value) {
+    const normalized = value?.trim().toLowerCase();
+    if (!normalized || normalized === "hosted")
+        return "hosted";
+    if (normalized === "local" ||
+        normalized === "local-file" ||
+        normalized === "local-files" ||
+        normalized === "files") {
+        return "local-files";
+    }
+    if (normalized === "self-hosted" ||
+        normalized === "selfhosted" ||
+        normalized === "custom" ||
+        normalized === "custom-url") {
+        return "self-hosted";
+    }
+    throw new Error('--mode must be one of "hosted", "local-files", or "self-hosted".');
+}
+function targetIncludesPlans(target) {
+    return normalizeKnownSkillTarget(target) === "visual-plans";
+}
+function targetsIncludePlans(targets) {
+    return targets.some(targetIncludesPlans);
+}
 async function resolveSkillTargets(parsed, options) {
     if (parsed.target || !shouldPrompt(parsed, options)) {
         return [parsed.target ?? "assets"];
@@ -2755,6 +2896,14 @@ export function parseSkillsArgs(argv) {
         }
         else if ((value = eat("--mcp-url")) !== undefined)
             out.mcpUrl = value;
+        else if ((value = eat("--mode")) !== undefined)
+            out.planMode = normalizePlanInstallMode(value);
+        else if (arg === "--hosted")
+            out.planMode = "hosted";
+        else if (arg === "--local" || arg === "--local-files")
+            out.planMode = "local-files";
+        else if (arg === "--self-hosted" || arg === "--custom-url")
+            out.planMode = "self-hosted";
         else if (arg === "--yes" || arg === "-y")
             out.yes = true;
         else if (arg === "--dry-run")
@@ -2785,6 +2934,9 @@ export function parseSkillsArgs(argv) {
     if (out.scope !== "user" && out.scope !== "project") {
         throw new Error("--scope must be either user or project.");
     }
+    if (out.planMode === "local-files" && out.mcpUrl) {
+        throw new Error("--mode local-files cannot be combined with --mcp-url.");
+    }
     return out;
 }
 function loadSkillTarget(target, onlySkillNames) {
@@ -2898,6 +3050,8 @@ function dryRunInstallCommand(parsed, target) {
         "--scope",
         parsed.scope,
     ];
+    if (parsed.planMode)
+        args.push("--mode", parsed.planMode);
     if (parsed.mcpUrl)
         args.push("--mcp-url", parsed.mcpUrl);
     if (parsed.instructions && !parsed.mcp)
@@ -3159,6 +3313,20 @@ async function connectAfterEnsure(installTarget, clients, parsed, options) {
 export async function addAgentNativeSkill(parsed, options = {}) {
     const target = parsed.target ?? "assets";
     const knownTarget = normalizeKnownSkillTarget(target);
+    const planMode = knownTarget === "visual-plans"
+        ? (parsed.planMode ?? (parsed.mcpUrl ? "self-hosted" : "hosted"))
+        : undefined;
+    if (parsed.planMode && knownTarget !== "visual-plans") {
+        throw new Error("--mode only applies to visual-plan / visual-recap.");
+    }
+    if (planMode === "local-files" && parsed.mcpUrl) {
+        throw new Error("--mode local-files cannot be combined with --mcp-url.");
+    }
+    if (planMode === "self-hosted" && !parsed.mcpUrl) {
+        throw new Error("--mode self-hosted requires --mcp-url <url>.");
+    }
+    const shouldRegisterMcp = parsed.mcp &&
+        !(knownTarget === "visual-plans" && planMode === "local-files");
     // For multi-skill bundles (the plan bundle), a single-skill target installs
     // only that skill. `installsRecap` controls the PR Visual Recap github-action
     // offer, which is only relevant when the recap skill is part of the install.
@@ -3258,12 +3426,15 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                 displayName: installTarget.displayName,
                 skillNames: installTarget.skillNames,
                 skillsAgents,
-                mcpUrl: installTarget.loaded.manifest.hosted.mcpUrl,
-                mcpClients: clients,
+                mcpUrl: knownTarget === "visual-plans" && planMode === "local-files"
+                    ? ""
+                    : installTarget.loaded.manifest.hosted.mcpUrl,
+                mcpClients: shouldRegisterMcp ? clients : [],
                 dryRun: true,
                 commands: [dryRunInstallCommand(parsed, target)],
                 githubActionPath,
                 githubActionSuggestedCommand,
+                planMode,
             };
         }
         finally {
@@ -3279,7 +3450,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     try {
         if (parsed.instructions) {
             if (skillsAgents.length === 0) {
-                if (!parsed.mcp) {
+                if (!shouldRegisterMcp) {
                     throw new Error("Skill instructions can only be installed for Codex or Claude Code clients. Use an MCP-capable client or omit --instructions-only.");
                 }
             }
@@ -3295,6 +3466,8 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                     scope: parsed.scope,
                     baseDir: options.baseDir ?? process.cwd(),
                     dryRun: parsed.dryRun,
+                    planMode,
+                    mcpUrl: installTarget.loaded.manifest.hosted.mcpUrl,
                 });
                 instructionSource = instructionsWritten[0];
                 commands.push(...instructionsWritten.map((dir) => `write ${dir}`));
@@ -3333,7 +3506,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             scope: parsed.scope,
             dryRun: Boolean(parsed.dryRun),
         });
-        if (parsed.mcp) {
+        if (shouldRegisterMcp) {
             commands.push(`npx @agent-native/core@latest app-skill ensure --manifest ${installTarget.loaded.file} --client ${parsed.client} --scope ${parsed.scope} --yes`);
             if (!parsed.dryRun) {
                 await ensureAppSkill(installTarget.loaded, {
@@ -3414,13 +3587,16 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             instructionSource,
             skillNames: installTarget.skillNames,
             skillsAgents,
-            mcpUrl: installTarget.loaded.manifest.hosted.mcpUrl,
-            mcpClients: clients,
+            mcpUrl: knownTarget === "visual-plans" && planMode === "local-files"
+                ? ""
+                : installTarget.loaded.manifest.hosted.mcpUrl,
+            mcpClients: shouldRegisterMcp ? clients : [],
             dryRun: parsed.dryRun,
             commands,
             written: instructionsWritten,
             connected,
             connectCommand,
+            planMode,
             githubActionPath,
             githubActionExisted,
             githubActionSuggestedCommand,
@@ -3454,6 +3630,7 @@ function skillStateJson(state) {
         installedHash: state.installedHash,
         latestHash: state.latestHash,
         metadataHash: state.metadataHash,
+        planMode: state.planMode,
     };
 }
 function formatSkillState(state) {
@@ -3464,6 +3641,13 @@ function formatSkillState(state) {
         : "";
     return `${state.skillName.padEnd(22)} ${status.padEnd(7)} ${state.scope}/${state.client} ${managed}${hashes}\n  ${state.path}`;
 }
+function planModeSummary(mode) {
+    if (mode === "local-files")
+        return "Local files - No sharing, all local.";
+    if (mode === "self-hosted")
+        return "Self-hosted/custom Plan app";
+    return "Hosted Plans - shareable links and comments";
+}
 function runSkillsStatusOrUpdate(parsed, options, update) {
     const before = collectSkillInstallStates(parsed, options);
     const changed = update ? updateSkillInstallStates(before, parsed.dryRun) : [];
@@ -3586,6 +3770,45 @@ export async function runSkills(argv, options = {}) {
             selectedAll: targets.length === skillPromptOptions().length,
             preselected,
         });
+        const includesPlans = targetsIncludePlans(targets);
+        if (parsed.planMode && !includesPlans) {
+            throw new Error("--mode only applies to visual-plan / visual-recap.");
+        }
+        if (includesPlans) {
+            if (!parsed.planMode && parsed.mcpUrl) {
+                parsed.planMode = "self-hosted";
+            }
+            if (!parsed.planMode && shouldPrompt(parsed, options)) {
+                const prompt = options.promptPlanMode ?? promptForPlanMode;
+                const mode = await prompt({ initialMode: "hosted" });
+                if (!mode) {
+                    telemetry.track("skills_cli cancelled", { step: "plan-mode" });
+                    return;
+                }
+                parsed.planMode = mode;
+            }
+            if (!parsed.planMode)
+                parsed.planMode = "hosted";
+            if (parsed.planMode === "self-hosted" && !parsed.mcpUrl) {
+                if (shouldPrompt(parsed, options)) {
+                    const prompt = options.promptPlanMcpUrl ?? promptForPlanMcpUrl;
+                    const mcpUrl = await prompt();
+                    if (!mcpUrl) {
+                        telemetry.track("skills_cli cancelled", {
+                            step: "plan-mcp-url",
+                        });
+                        return;
+                    }
+                    parsed.mcpUrl = mcpUrl;
+                }
+                else {
+                    throw new Error("--mode self-hosted requires --mcp-url <url> in non-interactive mode.");
+                }
+            }
+            telemetry.track("skills_cli plan mode selected", {
+                mode: parsed.planMode,
+            });
+        }
         const clients = await resolveSkillsClients(parsed, optionsWithTelemetry);
         if (!clients) {
             telemetry.track("skills_cli cancelled", { step: "clients" });
@@ -3684,6 +3907,11 @@ export async function runSkills(argv, options = {}) {
                 .filter((result) => result.local)
                 .flatMap((result) => result.commands)),
         ];
+        const planModes = [
+            ...new Set(results
+                .map((result) => result.planMode)
+                .filter((mode) => Boolean(mode))),
+        ];
         const authConnected = results.some((result) => result.connected);
         const pendingConnectCommands = [
             ...new Set(results
@@ -3720,6 +3948,9 @@ export async function runSkills(argv, options = {}) {
                 ? `MCP config           ${mcpClients.join(", ")}`
                 : "MCP config           not required",
             mcpUrls.length ? `MCP URL              ${mcpUrls.join(", ")}` : "",
+            planModes.length
+                ? `Plan mode            ${planModes.map(planModeSummary).join(", ")}`
+                : "",
             authConnected
                 ? "Authentication       completed"
                 : pendingConnectCommands.length