@agentprojectcontext/apx 1.33.0 → 1.34.0

package/src/core/apc/scaffold.js

@@ -11,12 +11,22 @@ import {
 } from "./parser.js";
 import { readApcContextSkill } from "./skill-sync.js";
 import { nowIso } from "../util/time.js";
+import {
+  apcDir,
+  apcProjectFile,
+  apcAgentsDir,
+  apcAgentFile,
+  agentsMdFile,
+} from "./paths.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Now under src/core/apc/ — one more "../" to escape than before.
 const PACKAGE_ROOT = path.resolve(__dirname, "..", "..", "..");
+// <packageRoot>/skills/<slug>/SKILL.md — the SLIM engine-side set: every skill
+// here is replicated verbatim into project IDE rule files (`apx skills add`) and
+// into ~/.<host>/skills/ (`apx skills sync`). The rich super-agent catalog lives
+// at src/core/runtime-skills/ and is intentionally NOT copied out.
 const BUNDLED_SKILLS_DIR = path.join(PACKAGE_ROOT, "skills");
-const RUNTIME_SKILLS_DIR = path.join(__dirname, "runtime-skills");
 
 export const SPEC_VERSION = "0.1.0";
 
@@ -26,12 +36,12 @@ export const SPEC_VERSION = "0.1.0";
 // install/update from the canonical APC repo (see src/interfaces/cli/postinstall.js).
 // ---------------------------------------------------------------------------
 
-// Bundled skills — apx lives in skills/apx/. apc-context is synced from
-// the canonical APC repo (../apc or GitHub) — never edited in APX.
+// Read one slim skill from <packageRoot>/skills/<slug>/SKILL.md. `apc-context`
+// is special-cased to refresh from the canonical APC repo if available.
 function readBundledSkill(slug) {
   if (slug === "apc-context") {
     const synced = readApcContextSkill();
-    return synced?.text || null;
+    if (synced?.text) return synced.text;
   }
   const file = path.join(BUNDLED_SKILLS_DIR, slug, "SKILL.md");
   if (!fs.existsSync(file)) return null;
@@ -132,19 +142,11 @@ const GLOBAL_SKILL_DIRS = [
   path.join(os.homedir(), ".agents", "skills"),    // Antigravity/other skills.sh adopters
 ];
 
-function readRuntimeSkillFiles() {
-  if (!fs.existsSync(RUNTIME_SKILLS_DIR)) return [];
-  return fs.readdirSync(RUNTIME_SKILLS_DIR)
-    .filter((name) => name.endsWith(".md"))
-    .sort()
-    .map((name) => ({
-      slug: path.basename(name, ".md"),
-      md: fs.readFileSync(path.join(RUNTIME_SKILLS_DIR, name), "utf8").trim(),
-    }));
-}
-
 // Install APX + APC context skills into IDE rule files. Returns an array of result objects.
 // targetIds: array of target ids to install; null = all project targets.
+// Writes the slim engine-side skill from <packageRoot>/skills/. The rich
+// super-agent set in src/core/runtime-skills/ is intentionally never written
+// into project IDE files.
 export function installIdeSkills(root, targetIds = null) {
   const apxRaw = readBundledSkill("apx");
   const apcRaw = readBundledSkill("apc-context");
@@ -195,36 +197,27 @@ export function installIdeSkills(root, targetIds = null) {
 // on the user's machine after `npm install -g .` (or `npm update -g apx`)
 // without anyone having to touch this file.
 //
-// Excluded: directory names starting with "." (e.g. .DS_Store), and any
-// runtime-only CLI skill that lives under src/core/runtime-skills/ — those
-// are loaded in-process at daemon startup and are NOT for IDE consumption.
-// Public: bundled skill slugs grouped by scope.
-//   public   → pushed to every global skill dir on install / sync (default).
-//   optional → not pushed by default; user opts in with --include-optional
-//              or `apx skills add <slug> --global` for one-off install.
-//   internal → APX-developer skills (mcp-builder, skill-builder, etc.); never
-//              pushed globally, only available to APX itself via the bundled
-//              copy. Avoids cluttering other IDEs with stuff their users won't
-//              run.
+// Excluded: directory names starting with "." (e.g. .DS_Store).
+// Every slug under <packageRoot>/skills/ is part of the slim engine set and
+// gets pushed to global dirs on `apx skills sync`. No scope filtering — the
+// dir IS the contract.
 export function listBundledSkillSlugs() {
   return discoverBundledSkills().map((s) => s.slug);
 }
 
 export function listBundledSkills() {
-  return discoverBundledSkills().map(({ slug, scope }) => ({ slug, scope }));
+  return discoverBundledSkills().map(({ slug }) => ({ slug }));
+}
+
+// Backwards-compat alias — every bundled slug here IS an engine slug now.
+export function listEngineSkills() {
+  return listBundledSkills();
 }
 
-// Tiny frontmatter peek — we only need the `scope:` field. Avoids pulling in
-// a full YAML parser for one optional line.
-function parseFrontmatterScope(md) {
-  if (!md.startsWith("---\n")) return "public";
-  const end = md.indexOf("\n---", 4);
-  if (end === -1) return "public";
-  const m = md.slice(4, end).match(/^scope:\s*(\w+)/m);
-  if (!m) return "public";
-  const s = m[1].toLowerCase();
-  if (s === "internal" || s === "optional" || s === "public") return s;
-  return "public";
+// Legacy slugs APX used to ship to global dirs but no longer does — exposed so
+// the CLI can report what `installGlobalSkills` will prune.
+export function listLegacyPruneSlugs() {
+  return [...PRUNE_LEGACY_SLUGS];
 }
 
 function discoverBundledSkills() {
@@ -237,65 +230,80 @@ function discoverBundledSkills() {
     const skillFile = path.join(root, entry.name, "SKILL.md");
     if (!fs.existsSync(skillFile)) continue;
     const md = fs.readFileSync(skillFile, "utf8");
-    out.push({ slug: entry.name, md, scope: parseFrontmatterScope(md) });
+    out.push({ slug: entry.name, md });
   }
   return out.sort((a, b) => a.slug.localeCompare(b.slug));
 }
 
-// Install bundled skills to every global ~/.../skills/ dir so Claude Code,
-// Cursor, Codex, and other IDEs see them.
+// Install the slim engine skill set to every global ~/.../skills/ dir
+// (Claude Code, Cursor, Codex, Antigravity/skills.sh). External engines only
+// need to know how to talk TO apx — not the full APX sub-skill catalog. The
+// rich bundled set in skills/<slug>/ stays in-repo for the APX super-agent.
+//
+// The set lives at skills/engines/<slug>/SKILL.md and is currently:
+//   apx, apx-mcp, apc-context.
 //
-// By default only `scope: public` skills land globally. Pass
-// includeOptional / includeInternal to push the other tiers (or call
-// `apx skills add <slug> --global` for a single one).
+// `includeOptional` / `includeInternal` are kept as no-op flags for backward
+// compatibility with `apx skills sync --include-…`; the slim set has no tiers.
 //
-// Pruning: if a slug that was previously installed has since been demoted to
-// internal/optional (or marked as non-public for the current call), we remove
-// the stale global copy unless prune=false. Keeps IDE skill lists clean.
+// Pruning: removes stale APX-shipped slugs that are no longer in the engine
+// set (the catalog of slugs APX has ever published, see PRUNE_LEGACY_SLUGS).
+// Skills the user installed themselves are NOT touched.
 //
 // Returns an array of { dir, skill, file, status, scope }.
-//   status ∈ {created, updated, unchanged, pruned, skipped}
+//   status ∈ {created, updated, unchanged, pruned}
+const PRUNE_LEGACY_SLUGS = [
+  "apx-agency-agents",
+  "apx-agent",
+  "apx-mcp-builder",
+  "apx-project",
+  "apx-routine",
+  "apx-runtime",
+  "apx-sessions",
+  "apx-skill-builder",
+  "apx-task",
+  "apx-telegram",
+  "apx-voice",
+  // Runtime CLI docs that previously leaked into global dirs — these are
+  // loaded in-process by the daemon and should NOT live on disk in IDE skill
+  // dirs.
+  "claude-code",
+  "codex-cli",
+  "opencode-cli",
+  "openrouter",
+];
+
 export function installGlobalSkills({
-  includeOptional = false,
-  includeInternal = false,
   prune = true,
+  // No-ops kept for CLI backward compatibility (the slim engine set has no tiers).
+  includeOptional: _includeOptional = false,
+  includeInternal: _includeInternal = false,
 } = {}) {
-  const all = discoverBundledSkills();
-  const wanted = all.filter((s) => {
-    if (s.scope === "internal") return includeInternal;
-    if (s.scope === "optional") return includeOptional;
-    return true; // public
-  });
+  const wanted = discoverBundledSkills();
   const wantedSlugs = new Set(wanted.map((s) => s.slug));
-  const knownSlugs = new Set(all.map((s) => s.slug));
 
   const results = [];
   for (const base of GLOBAL_SKILL_DIRS) {
-    // Push the wanted set.
-    for (const { slug, md, scope } of wanted) {
+    for (const { slug, md } of wanted) {
       const dest = path.join(base, slug, "SKILL.md");
       fs.mkdirSync(path.dirname(dest), { recursive: true });
       const existed = fs.existsSync(dest);
       const previous = existed ? fs.readFileSync(dest, "utf8") : null;
       if (previous === md) {
-        results.push({ dir: base, skill: slug, file: dest, status: "unchanged", scope });
+        results.push({ dir: base, skill: slug, file: dest, status: "unchanged", scope: "engine" });
         continue;
       }
       fs.writeFileSync(dest, md, "utf8");
-      results.push({ dir: base, skill: slug, file: dest, status: existed ? "updated" : "created", scope });
+      results.push({ dir: base, skill: slug, file: dest, status: existed ? "updated" : "created", scope: "engine" });
     }
-    // Prune anything WE shipped previously but should no longer be there
-    // (slug exists in the bundle but isn't `wanted` this run).
     if (prune) {
-      for (const { slug, scope } of all) {
+      for (const slug of PRUNE_LEGACY_SLUGS) {
         if (wantedSlugs.has(slug)) continue;
-        if (!knownSlugs.has(slug)) continue;
         const dest = path.join(base, slug, "SKILL.md");
         if (!fs.existsSync(dest)) continue;
         fs.unlinkSync(dest);
-        // Best-effort: drop the now-empty <slug>/ dir too.
         try { fs.rmdirSync(path.dirname(dest)); } catch {}
-        results.push({ dir: base, skill: slug, file: dest, status: "pruned", scope });
+        results.push({ dir: base, skill: slug, file: dest, status: "pruned", scope: "legacy" });
       }
     }
   }
@@ -421,7 +429,7 @@ function writeMigrateMd(apfDir, found) {
 // Get the stable APX storage ID for a project, generating one if it doesn't exist.
 // Called by the daemon when registering a project.
 export function getOrCreateApxId(root) {
-  const p = path.join(root, ".apc", "project.json");
+  const p = apcProjectFile(root);
   if (!fs.existsSync(p)) return null;
   let cfg;
   try { cfg = JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
@@ -437,7 +445,7 @@ export function initApf(directory, { name } = {}) {
   const root = path.resolve(directory);
   fs.mkdirSync(root, { recursive: true });
 
-  const apfDir = path.join(root, ".apc");
+  const apfDir = apcDir(root);
   fs.mkdirSync(path.join(apfDir, "agents"), { recursive: true });
   fs.mkdirSync(path.join(apfDir, "skills"), { recursive: true });
   fs.mkdirSync(path.join(apfDir, "commands"), { recursive: true });
@@ -467,7 +475,7 @@ export function initApf(directory, { name } = {}) {
     fs.writeFileSync(gitignore, APC_GITIGNORE);
   }
 
-  const agentsMd = path.join(root, "AGENTS.md");
+  const agentsMd = agentsMdFile(root);
   if (!fs.existsSync(agentsMd)) {
     fs.writeFileSync(agentsMd, AGENTS_MD_TEMPLATE);
   }
@@ -483,13 +491,13 @@ export function initApf(directory, { name } = {}) {
 }
 
 export function ensureAgentDir(root, slug) {
-  fs.mkdirSync(path.join(root, ".apc", "agents"), { recursive: true });
-  return path.join(root, ".apc", "agents");
+  fs.mkdirSync(apcAgentsDir(root), { recursive: true });
+  return apcAgentsDir(root);
 }
 
 // Write .apc/agents/<slug>.md — the canonical agent definition file.
 export function writeAgentFile(root, slug, fields, body = "") {
-  const dest = path.join(root, ".apc", "agents", `${slug}.md`);
+  const dest = apcAgentFile(root, slug);
   const lines = ["---"];
   const order = ["role", "model", "language", "description", "skills", "tools"];
   const written = new Set();
@@ -577,7 +585,7 @@ export function restoreVaultAgent(slug) {
 
 // Add a slug to the project's agents.imported list in project.json
 export function addImportedAgent(root, slug) {
-  const p = path.join(root, ".apc", "project.json");
+  const p = apcProjectFile(root);
   let cfg = {};
   try { cfg = JSON.parse(fs.readFileSync(p, "utf8")); } catch {}
   if (!cfg.agents) cfg.agents = {};

package/src/core/apc/skill-sync.js

@@ -4,9 +4,14 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-export const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+// __dirname is src/core/apc/ after the Phase 3 move (was src/core/ before).
+// Repo root is three levels up, not two.
+export const PACKAGE_ROOT = path.resolve(__dirname, "..", "..", "..");
 
+// Engine-side slim copy (replicated to ~/.<host>/skills/ by apx skills sync).
 export const APC_SKILL_REL = path.join("skills", "apc-context", "SKILL.md");
+// Runtime-internal copy (loaded by the super-agent — never published outside).
+export const APC_BUILTIN_SKILL_REL = path.join("src", "core", "runtime-skills", "apc-context", "SKILL.md");
 export const APC_SKILL_REMOTE =
   "https://raw.githubusercontent.com/agentprojectcontext/agentprojectcontext/main/skills/apc-context/SKILL.md";
 
@@ -93,5 +98,12 @@ export async function refreshApcContextSkill({ packageRoot = PACKAGE_ROOT, timeo
 
   fs.mkdirSync(path.dirname(dest), { recursive: true });
   fs.writeFileSync(dest, text, "utf8");
+
+  // Keep the runtime-internal copy (src/core/runtime-skills/apc-context/) in
+  // sync — that's where the super-agent loads it from.
+  const builtinDest = path.join(packageRoot, APC_BUILTIN_SKILL_REL);
+  fs.mkdirSync(path.dirname(builtinDest), { recursive: true });
+  fs.writeFileSync(builtinDest, text, "utf8");
+
   return { ok: true, source, refreshed: true };
 }