@ichintansoni/skills-master 0.1.7 → 0.1.9

package/README.md

@@ -14,10 +14,13 @@ npx @ichintansoni/skills-master list --class code            # browse the catalo
 npx @ichintansoni/skills-master search navigation
 npx @ichintansoni/skills-master update                        # pull newer skill versions
 npx @ichintansoni/skills-master remove swiftui-sheets
+npx @ichintansoni/skills-master sync                          # re-emit to match the current config
 npx @ichintansoni/skills-master status                        # what's installed, and has it drifted?
 npx @ichintansoni/skills-master doctor                        # same detection, but fails on drift
 ```
 
+`update` pulls newer skill content, but only ever re-emits to the targets a skill was *already* installed to. So adding a target to `skills-master.json` after the fact, or changing a `paths` override, leaves config and disk disagreeing with nothing to reconcile them. `sync` is that reconciliation — it treats the configured target set as the source of truth and makes disk match. Local edits are preserved unless you pass `--overwrite`. A target you *dropped* from config is reported but only deleted with `--prune`; a `paths` change is a move, so the old copy is cleaned up straight away rather than left for agents to load twice.
+
 `status` and `doctor` share their drift detection but answer different questions. `status` is an inventory — it lists every installed skill with its version, targets, and whether the output has been edited or deleted, works entirely offline, and always exits 0, so it is safe to pipe (`status --json`, `status --problems`, `status <name>…`). `doctor` is the gate: same findings, but it exits non-zero, which is what you want in CI.
 
 `add` writes, per detected tool:
@@ -29,7 +32,7 @@ npx @ichintansoni/skills-master doctor                        # same detection,
 | GitHub Copilot | `.github/instructions/<name>.instructions.md` |
 | AGENTS.md | a sentinel-marked block (your hand-written content is preserved) |
 
-Flags: `--target claude,cursor,copilot,agents|all` · `--with-pairs` (also install the paired code↔design skill) · `--dry-run` · `--overwrite` · `--content <dir>` (use a local skills checkout) · `--ref <git-ref>`.
+Flags: `--target claude,cursor,copilot,agents|all` · `--with-pairs` (also install the paired code↔design skill) · `--dry-run` · `--overwrite` · `--content <dir>` (use a local skills checkout) · `--ref <git-ref>`. An explicit `--target` or `--ref` is remembered in `skills-master.json`, and `--target` widens the configured set rather than replacing it.
 
 Claude Code users can alternatively install via the plugin marketplace:
 
@@ -38,8 +41,45 @@ Claude Code users can alternatively install via the plugin marketplace:
 /plugin install skills-master-apple-code@skills-master
 ```
 
+## Commands
+
+Run `skills-master <command> --help` for the full flag list on any of these.
+
+### Browsing the catalog
+
+| Command | What it does |
+|---|---|
+| `list` | List available skills. `--domain` · `--class` · `--category` · `--platform` · `--json` |
+| `search <query>` | Match a query against names, descriptions, facets, and tags. Spacing, hyphens and case are ignored, so `wear os`, `wear-os` and `WearOS` all find the same skills. `--json` |
+| `view <name>` | Show a skill's metadata and body. `--raw` prints the body alone; `--json` returns metadata *and* body in one document |
+
+### Working in a project
+
+| Command | What it does |
+|---|---|
+| `init` | Detect which tools the project uses and write `skills-master.json`. `--target` · `--commit` · `--ref` · `--force` |
+| `add <names…>` | Install skills by name, category, or class |
+| `update [names…]` | Re-install skills whose **content** changed upstream. Only touches targets a skill is already installed to |
+| `sync [names…]` | Re-emit to match the **current config** — new targets, moved `paths`, deleted files. `--overwrite` · `--prune` · `--dry-run` |
+| `remove <names…>` | Remove installed skills. `--target` removes from one tool only |
+| `status [names…]` | Inventory: versions, targets, and local-edit state. Offline, always exits 0. `--problems` · `--json` |
+| `doctor` | The same detection as `status`, but **exits non-zero** on drift — the CI gate. `--json` |
+
+`update` vs `sync` is the distinction worth knowing: `update` follows *content*, `sync` follows *config*.
+
+### Maintaining the library
+
+These operate on a skills checkout rather than a consuming project.
+
+| Command | What it does |
+|---|---|
+| `lint` | Validate the library: naming, reciprocal `pairs_with`, body caps, tag and source rules |
+| `new <domain/class/category/name>` | Scaffold a skill from the canonical template. `--force` |
+| `registry build` | Regenerate `registry.json`. `--check` fails on drift instead of rewriting |
+| `marketplace build` | Regenerate the Claude plugin marketplace. `--check` fails on drift |
+
 ## How it works
 
 Content lives in the [skills-master repo](https://github.com/iChintanSoni/skills-master) and is fetched on demand; the CLI compiles each skill into your tools' formats and records what it installed in `skills-master.json` + a lockfile so `update`/`remove` stay surgical. Generated files are committed to your repo by default, so teammates' IDEs pick them up without running anything.
 
-MIT licensed. Skill content is original prose that summarizes Apple's publicly documented best practices and links to the canonical docs — it does not reproduce Apple's copyrighted text or sample code.
+MIT licensed. Skill content is original prose that summarizes Apple's and Google's publicly documented best practices and links to the canonical docs — it does not reproduce either vendor's copyrighted text or sample code.

package/dist/bin.js

@@ -4,7 +4,7 @@
 import { Command } from "commander";
 
 // package.json
-var version = "0.1.7";
+var version = "0.1.9";
 
 // src/schema/projectConfig.ts
 import { z } from "zod";
@@ -1037,13 +1037,31 @@ function ensureGitignored(root, entries) {
   writeFileSync3(p, next, "utf8");
 }
 
+// src/util/targets.ts
+var VALID = new Set(ALL_TARGETS);
+function resolveTargets(cwd, configured, explicit) {
+  if (explicit?.length) return explicit;
+  if (configured.length) return configured;
+  const detected = detectTargets(cwd);
+  return detected.length ? detected : ALL_TARGETS;
+}
+function parseTargets(value) {
+  if (!value) return void 0;
+  if (value === "all") return ALL_TARGETS;
+  const ids = value.split(",").map((s) => s.trim()).filter(Boolean);
+  for (const id of ids) {
+    if (!VALID.has(id)) {
+      throw new Error(`Unknown target "${id}". Valid: ${[...VALID, "all"].join(", ")}.`);
+    }
+  }
+  return ids;
+}
+
 // src/commands/add.ts
 async function addCommand(opts) {
   const cfg = loadConfigOrDefault(opts.cwd);
   const hadConfig = loadConfig(opts.cwd) != null;
-  let targets = opts.targets?.length ? opts.targets : cfg.targets;
-  if (!targets.length) targets = detectTargets(opts.cwd);
-  if (!targets.length) targets = ALL_TARGETS;
+  const targets = resolveTargets(opts.cwd, cfg.targets, opts.targets);
   const content = await resolveContent({
     content: opts.content,
     ref: opts.ref ?? cfg.contentRef,
@@ -1110,6 +1128,23 @@ async function addCommand(opts) {
     if (!hadConfig) {
       saveConfig(opts.cwd, { ...cfg, targets });
       log.info("Wrote skills-master.json.");
+    } else {
+      const merged = [.../* @__PURE__ */ new Set([...cfg.targets, ...opts.targets ?? []])].sort();
+      const targetsChanged = opts.targets?.length != null && merged.join() !== [...cfg.targets].sort().join();
+      const refChanged = opts.ref != null && opts.ref !== cfg.contentRef;
+      if (targetsChanged || refChanged) {
+        const next = {
+          ...cfg,
+          targets: targetsChanged ? merged : cfg.targets,
+          contentRef: refChanged ? opts.ref : cfg.contentRef
+        };
+        saveConfig(opts.cwd, next);
+        const what = [
+          targetsChanged ? `targets: ${next.targets.join(", ")}` : null,
+          refChanged ? `ref: ${next.contentRef}` : null
+        ].filter(Boolean);
+        log.info(`Updated skills-master.json (${what.join(", ")}).`);
+      }
     }
     if (!cfg.commit) {
       ensureGitignored(
@@ -1288,16 +1323,34 @@ function doctorCommand(opts) {
   const problems = [];
   const note = (msg) => problems.push(msg);
   const cfg = loadConfig(opts.cwd);
-  if (!cfg) {
-    log.warn("No skills-master.json found \u2014 run `skills-master init`.");
-  } else {
-    log.info(`Config targets: ${cfg.targets.length ? cfg.targets.join(", ") : "(auto-detect)"}`);
-  }
   const lock = loadLockfile(opts.cwd);
   const diagnoses = diagnoseInstalled(opts.cwd, lock);
+  const emit = (report) => {
+    if (!opts.json) return report;
+    log.plain(
+      JSON.stringify(
+        {
+          ok: report.ok,
+          problems: report.problems,
+          skills: diagnoses,
+          configuredTargets: cfg?.targets ?? []
+        },
+        null,
+        2
+      )
+    );
+    return report;
+  };
+  if (!opts.json) {
+    if (!cfg) {
+      log.warn("No skills-master.json found \u2014 run `skills-master init`.");
+    } else {
+      log.info(`Config targets: ${cfg.targets.length ? cfg.targets.join(", ") : "(auto-detect)"}`);
+    }
+  }
   if (diagnoses.length === 0) {
-    log.info("No skills installed.");
-    return { problems, ok: true };
+    if (!opts.json) log.info("No skills installed.");
+    return emit({ problems, ok: true });
   }
   for (const skill of diagnoses) {
     for (const t of skill.targets) {
@@ -1314,14 +1367,16 @@ function doctorCommand(opts) {
       }
     }
   }
-  if (problems.length === 0) {
-    log.success(`All ${diagnoses.length} installed skill(s) look healthy.`);
-  } else {
-    for (const p of problems) log.warn(p);
-    log.plain(`
+  if (!opts.json) {
+    if (problems.length === 0) {
+      log.success(`All ${diagnoses.length} installed skill(s) look healthy.`);
+    } else {
+      for (const p of problems) log.warn(p);
+      log.plain(`
 ${problems.length} problem(s) found.`);
+    }
   }
-  return { problems, ok: problems.length === 0 };
+  return emit({ problems, ok: problems.length === 0 });
 }
 
 // src/commands/status.ts
@@ -1378,6 +1433,147 @@ function statusCommand(opts) {
   return report;
 }
 
+// src/commands/sync.ts
+async function syncCommand(opts) {
+  const cfg = loadConfigOrDefault(opts.cwd);
+  const lock = loadLockfile(opts.cwd);
+  const targets = resolveTargets(opts.cwd, cfg.targets);
+  const paths = resolvePaths(cfg);
+  const prefix = opts.dryRun ? "[dry-run] " : "";
+  const all = Object.keys(lock.skills).sort();
+  const names = opts.names?.length ? all.filter((n) => opts.names.includes(n)) : all;
+  const result = {
+    synced: [],
+    skipped: [],
+    addedTargets: [],
+    orphaned: [],
+    stale: [],
+    pruned: false
+  };
+  if (all.length === 0) {
+    log.info("No skills installed \u2014 run `skills-master add <name>`.");
+    return result;
+  }
+  if (names.length === 0) {
+    log.warn("No installed skills match.");
+    return result;
+  }
+  const edited = new Map(
+    diagnoseInstalled(opts.cwd, lock).map((d) => [d.name, d.targets.some((t) => t.edited)])
+  );
+  const content = await resolveContent({
+    content: opts.content,
+    ref: opts.ref ?? cfg.contentRef,
+    cwd: opts.cwd
+  });
+  log.info(`Syncing ${names.length} skill(s) to targets: ${targets.join(", ")}`);
+  const addedTargets = /* @__PURE__ */ new Set();
+  const pruneNames = [];
+  const pruneTargets = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    const locked = lock.skills[name];
+    const installedTo = Object.keys(locked.emitted);
+    const orphans = installedTo.filter((t) => !targets.includes(t));
+    if (orphans.length) {
+      result.orphaned.push({ name, targets: orphans });
+      pruneNames.push(name);
+      for (const t of orphans) pruneTargets.add(t);
+    }
+    if (edited.get(name) && !opts.overwrite) {
+      log.warn(`${prefix}"${name}" has local edits \u2014 skipping (use --overwrite to replace).`);
+      result.skipped.push(name);
+      continue;
+    }
+    let skill;
+    try {
+      skill = content.loadSkill(name);
+    } catch (err) {
+      if (err instanceof SkillNotFoundError) {
+        log.warn(`"${name}" no longer exists in the content library \u2014 leaving it in place.`);
+      } else {
+        log.error(`Failed to load "${name}": ${err instanceof Error ? err.message : String(err)}`);
+      }
+      result.skipped.push(name);
+      continue;
+    }
+    for (const t of targets) if (!locked.emitted[t]) addedTargets.add(t);
+    const prevFiles = /* @__PURE__ */ new Set();
+    const prevBlocks = /* @__PURE__ */ new Map();
+    for (const t of targets) {
+      const e = locked.emitted[t];
+      if (!e) continue;
+      for (const f of e.files) prevFiles.add(f);
+      if (e.block) prevBlocks.set(t, e.block);
+    }
+    const emitted = installSkill(opts.cwd, skill, targets, paths, {
+      dryRun: opts.dryRun,
+      overwrite: true
+      // edits were already checked above
+    });
+    const nowFiles = /* @__PURE__ */ new Set();
+    for (const e of Object.values(emitted.locked.emitted)) {
+      for (const f of e.files) nowFiles.add(f);
+    }
+    const staleFiles = [...prevFiles].filter((f) => !nowFiles.has(f));
+    const staleBlocks = [...prevBlocks].filter(([t, b]) => emitted.locked.emitted[t]?.block !== b).map(([, b]) => b);
+    if (staleFiles.length || staleBlocks.length) {
+      result.stale.push({ name, files: staleFiles, blocks: staleBlocks });
+    }
+    if (!opts.dryRun) {
+      lock.skills[name] = {
+        ...emitted.locked,
+        emitted: { ...locked.emitted, ...emitted.locked.emitted }
+      };
+    }
+    result.synced.push(name);
+    for (const r of emitted.results) {
+      if (r.action === "unchanged") continue;
+      const tag = r.mode === "block" ? `${r.path} [${r.blockId}]` : r.path;
+      log.info(`${prefix}${r.action.padEnd(9)} ${tag}`);
+    }
+  }
+  result.addedTargets = [...addedTargets].sort();
+  if (!opts.dryRun) saveLockfile(opts.cwd, lock);
+  if (result.orphaned.length) {
+    const list = [...pruneTargets].sort().join(", ");
+    if (opts.prune) {
+      removeCommand({
+        cwd: opts.cwd,
+        names: pruneNames,
+        targets: [...pruneTargets],
+        dryRun: opts.dryRun
+      });
+      result.pruned = true;
+    } else {
+      log.warn(
+        `${result.orphaned.length} skill(s) still have output for target(s) the config no longer lists: ${list}. Re-run with --prune to remove.`
+      );
+    }
+  }
+  if (result.stale.length) {
+    const gone = [];
+    for (const f of result.stale.flatMap((s) => s.files)) {
+      if (removeWholeFile(opts.cwd, f, opts.dryRun)) {
+        gone.push(f);
+        log.info(`${prefix}moved-from ${f}`);
+      }
+    }
+    pruneEmptyDirs(opts.cwd, gone, opts.dryRun);
+    for (const s of result.stale) {
+      for (const b of s.blocks) {
+        if (removeBlockFromFile(opts.cwd, b, s.name, opts.dryRun)) {
+          log.info(`${prefix}unblocked  ${b} [${s.name}]`);
+        }
+      }
+    }
+  }
+  const bits = [`${result.synced.length} synced`];
+  if (result.addedTargets.length) bits.push(`new target(s): ${result.addedTargets.join(", ")}`);
+  if (result.skipped.length) bits.push(`${result.skipped.length} skipped`);
+  log.success(`${prefix}${bits.join(", ")}.`);
+  return result;
+}
+
 // src/core/search-text.ts
 function searchNormalize(value) {
   return value.toLowerCase().replace(/[^a-z0-9]+/g, "");
@@ -1437,6 +1633,10 @@ async function searchCommand(opts) {
       [s.name, s.description, s.domain, s.category, s.class, ...s.tags].join(" ")
     ).includes(q)
   );
+  if (opts.json) {
+    log.plain(JSON.stringify(hits, null, 2));
+    return hits;
+  }
   if (hits.length === 0) {
     log.info(`No matches for "${opts.query}".`);
     return hits;
@@ -1453,6 +1653,24 @@ async function viewCommand(opts) {
   const content = await resolveContent({ content: opts.content, ref: opts.ref, cwd: opts.cwd });
   const skill = content.loadSkill(opts.name);
   const xm = skill.frontmatter["x-skills-master"];
+  if (opts.json) {
+    log.plain(
+      JSON.stringify(
+        {
+          name: skill.name,
+          description: skill.frontmatter.description,
+          globs: skill.frontmatter.globs ?? [],
+          tags: skill.frontmatter.tags ?? [],
+          ...xm,
+          resources: Object.entries(skill.resources).filter(([, v]) => v).map(([k]) => k),
+          body: skill.body
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
   if (opts.raw) {
     log.plain(skill.body);
     return;
@@ -1922,20 +2140,6 @@ async function newSkillCommand(opts) {
   return skillMd;
 }
 
-// src/util/targets.ts
-var VALID = new Set(ALL_TARGETS);
-function parseTargets(value) {
-  if (!value) return void 0;
-  if (value === "all") return ALL_TARGETS;
-  const ids = value.split(",").map((s) => s.trim()).filter(Boolean);
-  for (const id of ids) {
-    if (!VALID.has(id)) {
-      throw new Error(`Unknown target "${id}". Valid: ${[...VALID, "all"].join(", ")}.`);
-    }
-  }
-  return ids;
-}
-
 // src/bin.ts
 async function run(fn, exitOnFalse = false) {
   try {
@@ -1973,15 +2177,24 @@ program.command("list").description("List available skills").option("--domain <d
     })
   )
 );
-program.command("search <query>").description("Search skills by name, description, tags").option("--content <dir>", "local skills directory").option("--ref <ref>", "content git ref (tag/branch/sha)").action(
-  (query, opts) => run(() => searchCommand({ cwd: process.cwd(), query, content: opts.content, ref: opts.ref }))
+program.command("search <query>").description("Search skills by name, description, tags").option("--content <dir>", "local skills directory").option("--ref <ref>", "content git ref (tag/branch/sha)").option("--json", "machine-readable output").action(
+  (query, opts) => run(
+    () => searchCommand({
+      cwd: process.cwd(),
+      query,
+      content: opts.content,
+      ref: opts.ref,
+      json: opts.json
+    })
+  )
 );
-program.command("view <name>").description("Show a skill's metadata and body").option("--raw", "print the raw SKILL.md body").option("--content <dir>", "local skills directory").option("--ref <ref>", "content git ref (tag/branch/sha)").action(
+program.command("view <name>").description("Show a skill's metadata and body").option("--raw", "print the raw SKILL.md body").option("--content <dir>", "local skills directory").option("--ref <ref>", "content git ref (tag/branch/sha)").option("--json", "machine-readable output (metadata plus body)").action(
   (name, opts) => run(
     () => viewCommand({
       cwd: process.cwd(),
       name,
       raw: opts.raw,
+      json: opts.json,
       content: opts.content,
       ref: opts.ref
     })
@@ -2023,6 +2236,19 @@ program.command("remove <names...>").description("Remove installed skills").opti
     })
   )
 );
+program.command("sync").description("Re-emit installed skills to match the current config (new targets, moved paths)").argument("[names...]", "limit the sync to these installed skills").option("--content <dir>", "local skills directory").option("--ref <git-ref>", "content ref to read from").option("--overwrite", "replace locally edited outputs").option("--prune", "delete outputs for targets the config no longer lists").option("--dry-run", "show what would change without writing").action(
+  (names, opts) => run(
+    () => syncCommand({
+      cwd: process.cwd(),
+      names,
+      content: opts.content,
+      ref: opts.ref,
+      overwrite: opts.overwrite,
+      prune: opts.prune,
+      dryRun: opts.dryRun
+    })
+  )
+);
 program.command("status").description("Show installed skills: versions, targets, and local-edit state").argument("[names...]", "limit the report to these skills").option("--problems", "show only skills that are edited or missing files").option("--json", "machine-readable output").action(
   (names, opts) => run(
     () => statusCommand({
@@ -2033,7 +2259,7 @@ program.command("status").description("Show installed skills: versions, targets,
     })
   )
 );
-program.command("doctor").description("Check installed skills for drift and missing files").action(() => run(() => doctorCommand({ cwd: process.cwd() }).ok, true));
+program.command("doctor").description("Check installed skills for drift and missing files").option("--json", "machine-readable output").action((opts) => run(() => doctorCommand({ cwd: process.cwd(), json: opts.json }).ok, true));
 program.command("lint").description("Validate the skill library (maintainer command)").option("--content <dir>", "local skills directory").action((opts) => run(() => lintCommand({ cwd: process.cwd(), content: opts.content }), true));
 program.command("new <spec>").description("Scaffold a new skill: domain/class/category/name (maintainer command)").option("--content <dir>", "local skills directory").option("--force", "overwrite an existing skill directory").action(
   (spec, opts) => run(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ichintansoni/skills-master",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Install tool-agnostic Apple & Android development skills into any AI coding tool (Claude Code, Cursor, Copilot, AGENTS.md).",
   "keywords": [
     "skills",