stackfit 0.0.0-stage → 0.1.1

package/schemas/stackfit.local.schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "stackfit machine profiles (stackfit.local.json, gitignored)",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "machines"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "machines": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "match",
+          "roots"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Label printed when this machine profile is selected."
+          },
+          "match": {
+            "type": "object",
+            "required": [
+              "platform"
+            ],
+            "properties": {
+              "platform": {
+                "type": "string",
+                "enum": [
+                  "win32",
+                  "darwin",
+                  "linux"
+                ],
+                "description": "Node.js process.platform value."
+              },
+              "hostname": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Optional exact hostname match (os.hostname())."
+              }
+            },
+            "additionalProperties": false
+          },
+          "roots": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": "Absolute or ~-relative directories containing Git projects to sync with --all."
+          },
+          "projects": {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/projectEntry"
+            },
+            "description": "Optional projects to sync under roots. Omit to sync every Git repo in roots. Use { name, scaffold: false } for adapter-only local sync without docs/agent scaffolding."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "$schema": {
+      "type": "string"
+    }
+  },
+  "$defs": {
+    "projectEntry": {
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "object",
+          "required": [
+            "name"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "minLength": 1
+            },
+            "scaffold": {
+              "type": "boolean",
+              "default": true,
+              "description": "When false, sync shared skills/adapters only and keep CLAUDE.md + docs/agent/ local-gitignored. init is skipped."
+            },
+            "packs": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              },
+              "uniqueItems": true,
+              "description": "Extra packs for this project on this machine. Useful for scaffold:false repos whose docs/agent/config.json is not read."
+            },
+            "excludePacks": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              },
+              "uniqueItems": true,
+              "description": "Auto-detected packs to skip for this project on this machine."
+            },
+            "skills": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              },
+              "uniqueItems": true,
+              "description": "Individual catalog skills to add for this project on this machine."
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/stackfit.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "stackfit catalog registry (stackfit.json)",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "skills",
+    "packs"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 3
+    },
+    "projectConfigPath": {
+      "type": "string",
+      "description": "Where projects keep their config. Default docs/agent/config.json."
+    },
+    "skills": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true,
+      "description": "Enabled catalog. A skill reaches a project only through a pack or an explicit project `skills` entry."
+    },
+    "packs": {
+      "type": "object",
+      "description": "Named skill groups. `always` packs go to every project; `detect` packs are auto-selected from package.json dependencies or root/subfolder files; packs with neither are opt-in only.",
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "skills"
+        ],
+        "properties": {
+          "description": {
+            "type": "string"
+          },
+          "always": {
+            "type": "boolean"
+          },
+          "detect": {
+            "type": "object",
+            "properties": {
+              "dependencies": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "uniqueItems": true
+              },
+              "files": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "uniqueItems": true
+              }
+            },
+            "additionalProperties": false
+          },
+          "skills": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "uniqueItems": true
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "adapters": {
+      "type": "object",
+      "required": [
+        "agents",
+        "commands",
+        "rules"
+      ],
+      "properties": {
+        "agents": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        },
+        "commands": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "$schema": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": false,
+  "$id": "https://unpkg.com/stackfit/schemas/stackfit.schema.json"
+}

package/src/audit.mjs

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadRegistry, loadSources } from "./catalog.mjs";
+import { effectiveMetadata, listingCost } from "./render.mjs";
+import { charsToTokens } from "./report.mjs";
+
+const STALE_DAYS = 180;
+const DESCRIPTION_LIMIT = 1024;
+
+export function auditCatalog(catalog, { now = Date.now() } = {}) {
+  const registry = loadRegistry(catalog);
+  const sources = loadSources(catalog);
+  const errors = [];
+  const warnings = [];
+  const directories = existsSync(catalog.skills)
+    ? readdirSync(catalog.skills, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && !entry.name.startsWith("_") && !entry.name.startsWith("."))
+      .map((entry) => entry.name)
+      .sort()
+    : [];
+
+  const metadataByName = new Map();
+  for (const name of directories) {
+    const skillPath = resolve(catalog.skills, name, "SKILL.md");
+    if (!existsSync(skillPath)) {
+      errors.push(`${name}: missing SKILL.md`);
+      continue;
+    }
+    const content = readFileSync(skillPath, "utf8");
+    const metadata = effectiveMetadata(content, sources.skills[name]?.render?.frontmatter);
+    metadataByName.set(name, metadata);
+    if (!metadata.name || !metadata.description) errors.push(`${name}: frontmatter needs name and description`);
+    if (metadata.name && metadata.name !== name) errors.push(`${name}: frontmatter name is '${metadata.name}' (directory name must match, or set render.frontmatter.name)`);
+    if (metadata.description?.length > DESCRIPTION_LIMIT) warnings.push(`${name}: description is ${metadata.description.length} chars (claude.ai rejects > ${DESCRIPTION_LIMIT})`);
+    if (content.split("\n").length > 500) warnings.push(`${name}: SKILL.md over 500 lines; move details into referenced files`);
+  }
+
+  for (const [name, provenance] of Object.entries(sources.skills)) {
+    if (!registry.skills.includes(name) && !directories.includes(name)) warnings.push(`skill-sources.json: '${name}' is neither enabled nor in skills/`);
+    if (provenance.kind === "external" && !provenance.source) warnings.push(`${name}: external origin is not recorded; refresh is disabled`);
+    if (!provenance.reviewed) warnings.push(`${name}: no 'reviewed' date in skill-sources.json`);
+    else {
+      const age = (now - Date.parse(provenance.reviewed)) / 86_400_000;
+      if (age > STALE_DAYS) warnings.push(`${name}: last reviewed ${provenance.reviewed} (${Math.floor(age)} days ago); check it is still current and worth its context`);
+    }
+  }
+
+  for (const name of registry.skills) {
+    if (directories.includes(name)) {
+      if (!sources.skills[name]) warnings.push(`${name}: no skill-sources.json entry (add kind: custom or external)`);
+      continue;
+    }
+    if (sources.skills[name]?.source) errors.push(`${name}: enabled but not vendored yet; run \`stackfit refresh --skill ${name}\``);
+    else errors.push(`stackfit.json: unknown skill '${name}'`);
+  }
+  for (const name of directories) {
+    if (!registry.skills.includes(name)) warnings.push(`${name}: in skills/ but not enabled in stackfit.json`);
+  }
+
+  const packed = new Set();
+  for (const [packName, pack] of Object.entries(registry.packs)) {
+    for (const name of pack.skills) {
+      if (!registry.skills.includes(name)) errors.push(`pack '${packName}': skill '${name}' is not enabled in stackfit.json`);
+      packed.add(name);
+    }
+    if (pack.always && pack.detect) warnings.push(`pack '${packName}': 'always' makes 'detect' redundant`);
+  }
+  for (const name of registry.skills) {
+    if (!packed.has(name)) warnings.push(`${name}: enabled but in no pack; it only reaches projects that list it under 'skills'`);
+  }
+  for (const [kind, files] of Object.entries(registry.adapters)) {
+    for (const file of files) if (!existsSync(resolve(catalog.root, kind, file))) errors.push(`unknown adapter ${kind}/${file}`);
+  }
+
+  const cost = (names) => names.reduce((total, name) => total + listingCost(metadataByName.get(name), name), 0);
+  const packCosts = Object.entries(registry.packs).map(([name, pack]) => ({ name, always: Boolean(pack.always), tokens: charsToTokens(cost(pack.skills)) }));
+  return { errors, warnings, skills: directories.length, packs: packCosts, adapters: Object.values(registry.adapters).flat().length, totalTokens: charsToTokens(cost([...packed])) };
+}
+
+export function printAudit(result) {
+  for (const warning of result.warnings) console.warn(`warning: ${warning}`);
+  for (const error of result.errors) console.error(`error: ${error}`);
+  console.log(`Audited ${result.skills} skills, ${result.packs.length} packs, and ${result.adapters} adapters.`);
+  console.log("Always-loaded description cost per pack (approx. tokens; manual-only skills cost 0):");
+  for (const pack of result.packs) console.log(`  ${pack.name.padEnd(18)} ${String(pack.tokens).padStart(5)}${pack.always ? "  (every project)" : ""}`);
+  console.log(`  ${"all packs".padEnd(18)} ${String(result.totalTokens).padStart(5)}`);
+}

package/src/catalog.mjs

@@ -0,0 +1,115 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, resolve } from "node:path";
+
+export const REGISTRY_FILE = "stackfit.json";
+export const LOCAL_FILE = "stackfit.local.json";
+export const SOURCES_FILE = "skill-sources.json";
+export const SOURCES_LOCK_FILE = "skill-sources.lock.json";
+
+export function loadJson(path, fallback = undefined) {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(`Invalid JSON in ${path}: ${error.message}`);
+  }
+}
+
+// `.env` files never override variables already set in the shell.
+export function loadEnvFile(path) {
+  if (!existsSync(path)) return;
+  for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
+    const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+    if (!match || line.trim().startsWith("#")) continue;
+    const [, key, raw] = match;
+    if (process.env[key] !== undefined) continue;
+    process.env[key] = raw.replace(/^(['"])(.*)\1$/, "$2");
+  }
+}
+
+export function expandHome(pathValue, base = process.cwd()) {
+  const trimmed = pathValue.trim();
+  if (!trimmed) throw new Error("Empty path");
+  if (trimmed === "~") return homedir();
+  if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) return resolve(homedir(), trimmed.slice(2));
+  return isAbsolute(trimmed) ? resolve(trimmed) : resolve(base, trimmed);
+}
+
+function findUp(start, file) {
+  let current = resolve(start);
+  while (true) {
+    if (existsSync(resolve(current, file))) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+// Catalog = the folder holding stackfit.json, skills/, rules/, commands/, agents/.
+// Resolution: --catalog, then STACKFIT_CATALOG (shell or ./.env), then the nearest
+// stackfit.json above the working directory, then ~/.stackfit.
+export function resolveCatalog(explicit) {
+  loadEnvFile(resolve(process.cwd(), ".env"));
+  const candidates = [
+    explicit && expandHome(explicit),
+    process.env.STACKFIT_CATALOG && expandHome(process.env.STACKFIT_CATALOG),
+    findUp(process.cwd(), REGISTRY_FILE),
+    resolve(homedir(), ".stackfit"),
+  ].filter(Boolean);
+  const root = candidates.find((path) => existsSync(resolve(path, REGISTRY_FILE)));
+  if (!root) {
+    const tried = explicit || process.env.STACKFIT_CATALOG;
+    throw new Error(
+      tried
+        ? `No ${REGISTRY_FILE} in ${expandHome(tried)}`
+        : `No catalog found. Create one with \`stackfit catalog init\` (your own skills) or \`stackfit catalog init --starter\` (curated packs), or point to one with STACKFIT_CATALOG / --catalog.`,
+    );
+  }
+  loadEnvFile(resolve(root, ".env"));
+  return catalogPaths(root);
+}
+
+export function catalogPaths(root) {
+  return {
+    root,
+    registryPath: resolve(root, REGISTRY_FILE),
+    localPath: process.env.STACKFIT_LOCAL_CONFIG ? resolve(process.env.STACKFIT_LOCAL_CONFIG) : resolve(root, LOCAL_FILE),
+    sourcesPath: resolve(root, SOURCES_FILE),
+    sourcesLockPath: resolve(root, SOURCES_LOCK_FILE),
+    skills: resolve(root, "skills"),
+    agents: resolve(root, "agents"),
+    commands: resolve(root, "commands"),
+    rules: resolve(root, "rules"),
+  };
+}
+
+export function loadRegistry(catalog) {
+  const registry = loadJson(catalog.registryPath);
+  if (registry.schemaVersion !== 3) throw new Error(`${REGISTRY_FILE}: unsupported schemaVersion ${registry.schemaVersion} (expected 3)`);
+  return {
+    projectConfigPath: "docs/agent/config.json",
+    packs: {},
+    ...registry,
+    adapters: { agents: [], commands: [], rules: [], ...(registry.adapters ?? {}) },
+  };
+}
+
+export function loadSources(catalog) {
+  return loadJson(catalog.sourcesPath, { schemaVersion: 2, skills: {} });
+}
+
+const warned = new Set();
+
+// `{{env:NAME}}` in commands, rules, and agents is filled from the environment at sync time,
+// so personal values (emails, org names) live in the catalog's gitignored .env.
+export function expandEnv(content, origin) {
+  return content.replace(/\{\{env:([A-Za-z_][A-Za-z0-9_]*)\}\}/g, (placeholder, name) => {
+    if (process.env[name] !== undefined) return process.env[name];
+    if (!warned.has(name)) {
+      warned.add(name);
+      console.warn(`warning: ${origin} uses {{env:${name}}} but ${name} is not set; left as-is`);
+    }
+    return placeholder;
+  });
+}

package/src/detect.mjs

@@ -0,0 +1,110 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { basename, resolve } from "node:path";
+
+const SCAN_SKIP = new Set(["node_modules", "dist", "build", "out", "coverage", "target", "vendor", "venv", "__pycache__"]);
+
+// Root, every top-level folder, and one level below it: covers `web/`, `apps/*`, `packages/*`.
+export function candidateDirectories(projectPath) {
+  const children = (directory) => {
+    try {
+      return readdirSync(directory, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && !SCAN_SKIP.has(entry.name))
+        .map((entry) => resolve(directory, entry.name));
+    } catch {
+      return [];
+    }
+  };
+  const level1 = children(projectPath);
+  return [projectPath, ...level1, ...level1.flatMap(children)];
+}
+
+const normalize = (name) => name.trim().toLowerCase();
+
+// Manifest readers return dependency names. Regex-based on purpose: detection only needs names.
+const MANIFESTS = {
+  "package.json": (text) => {
+    const manifest = JSON.parse(text);
+    return ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]
+      .flatMap((field) => Object.keys(manifest[field] ?? {}));
+  },
+  "requirements.txt": (text) => text.split(/\r?\n/)
+    .map((line) => line.replace(/#.*/, "").trim())
+    .filter((line) => line && !line.startsWith("-"))
+    .map((line) => line.split(/[\s<>=!~;[]/)[0]),
+  "pyproject.toml": (text) => [...text.matchAll(/^\s*["']([A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:[<>=!~;[\s"']|$)/gm)].map((match) => match[1])
+    .concat([...text.matchAll(/^\s*([A-Za-z0-9][A-Za-z0-9._-]*)\s*=\s*(?:["'{^~*\d])/gm)].map((match) => match[1])),
+  "go.mod": (text) => [...text.matchAll(/^\s*(?:require\s+)?([a-z0-9.-]+\.[a-z]{2,}\/[^\s]+)\s+v[\d.]/gm)].map((match) => match[1]),
+  "Cargo.toml": (text) => {
+    const names = [];
+    let inDeps = false;
+    for (const line of text.split(/\r?\n/)) {
+      const section = line.match(/^\s*\[([^\]]+)\]/);
+      if (section) inDeps = /(^|\.)(dev-|build-)?dependencies$/.test(section[1]);
+      else if (inDeps) {
+        const key = line.match(/^\s*([A-Za-z0-9_-]+)\s*=/);
+        if (key) names.push(key[1]);
+      }
+    }
+    return names;
+  },
+  "composer.json": (text) => {
+    const manifest = JSON.parse(text);
+    return [...Object.keys(manifest.require ?? {}), ...Object.keys(manifest["require-dev"] ?? {})];
+  },
+};
+
+export function detectionSignals(projectPath) {
+  const dependencies = new Set();
+  const files = new Set();
+  for (const directory of candidateDirectories(projectPath)) {
+    let entries;
+    try {
+      entries = readdirSync(directory);
+    } catch {
+      continue;
+    }
+    for (const name of entries) {
+      files.add(name);
+      const reader = MANIFESTS[name] ?? (/^requirements[-.\w]*\.txt$/.test(name) ? MANIFESTS["requirements.txt"] : null);
+      if (!reader) continue;
+      try {
+        for (const dependency of reader(readFileSync(resolve(directory, name), "utf8"))) dependencies.add(normalize(dependency));
+      } catch {
+        // An unreadable manifest simply contributes no signals.
+      }
+    }
+  }
+  return { dependencies, files };
+}
+
+export function packMatches(pack, signals) {
+  const detect = pack.detect ?? {};
+  return (detect.dependencies ?? []).some((name) => signals.dependencies.has(normalize(name)))
+    || (detect.files ?? []).some((name) => signals.files.has(name));
+}
+
+// Packs are selected by: always-on, explicit request, or auto-detection (packs without
+// `detect` are opt-in only). Explicit skills are added, disabledSharedSkills removed last.
+export function resolveSelection(projectPath, registry, projectConfig = {}, localSelection = {}) {
+  const packs = registry.packs ?? {};
+  const known = new Set(registry.skills);
+  const requested = new Set([...(projectConfig.packs ?? []), ...(localSelection.packs ?? [])]);
+  const excluded = new Set([...(projectConfig.excludePacks ?? []), ...(localSelection.excludePacks ?? [])]);
+  for (const name of [...requested, ...excluded]) {
+    if (!packs[name]) throw new Error(`${basename(projectPath)}: unknown pack '${name}'`);
+  }
+  const autodetect = projectConfig.detect !== false;
+  const signals = autodetect ? detectionSignals(projectPath) : null;
+  const selected = Object.entries(packs)
+    .filter(([name, pack]) => pack.always
+      || requested.has(name)
+      || (autodetect && pack.detect && !excluded.has(name) && packMatches(pack, signals)))
+    .map(([name]) => name);
+  const skills = new Set(selected.flatMap((name) => packs[name].skills));
+  for (const name of [...(projectConfig.skills ?? []), ...(localSelection.skills ?? [])]) {
+    if (!known.has(name)) throw new Error(`${basename(projectPath)}: unknown shared skill '${name}'`);
+    skills.add(name);
+  }
+  for (const name of projectConfig.disabledSharedSkills ?? []) skills.delete(name);
+  return { packs: selected, skills: [...skills].filter((name) => known.has(name)).sort() };
+}

package/src/projects.mjs

@@ -0,0 +1,117 @@
+import { existsSync, readdirSync } from "node:fs";
+import { hostname, platform } from "node:os";
+import { basename, dirname, resolve } from "node:path";
+import { expandHome, loadJson } from "./catalog.mjs";
+
+export function currentMachineIdentity() {
+  return {
+    platform: process.env.STACKFIT_PLATFORM || platform(),
+    hostname: process.env.STACKFIT_HOSTNAME || hostname(),
+  };
+}
+
+function scoreMachineMatch(entry, identity) {
+  const match = entry.match ?? {};
+  if (match.platform !== identity.platform) return -1;
+  if (match.hostname) return match.hostname.toLowerCase() === identity.hostname.toLowerCase() ? 2 : -1;
+  return 1;
+}
+
+export function resolveMachineProfile(localConfig, identity = currentMachineIdentity()) {
+  if (!localConfig) return null;
+  if (localConfig.schemaVersion !== 1) throw new Error("Unsupported stackfit.local.json schemaVersion");
+  if (!Array.isArray(localConfig.machines) || !localConfig.machines.length) {
+    throw new Error("stackfit.local.json must declare at least one machine");
+  }
+  let best = null;
+  let bestScore = -1;
+  for (const entry of localConfig.machines) {
+    const score = scoreMachineMatch(entry, identity);
+    if (score > bestScore) {
+      best = entry;
+      bestScore = score;
+    }
+  }
+  if (!best) {
+    throw new Error(
+      `No stackfit.local.json machine matches ${identity.platform} hostname=${identity.hostname}.`
+      + " Update the local file or pass --project/--root.",
+    );
+  }
+  return best;
+}
+
+function discoverProjects(root, catalogRoot) {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => resolve(root, entry.name))
+    .filter((path) => path !== catalogRoot && existsSync(resolve(path, ".git")))
+    .sort();
+}
+
+function normalizeProjectEntry(entry) {
+  if (typeof entry === "string") return { name: entry, scaffold: true, selection: {} };
+  if (entry && typeof entry === "object" && typeof entry.name === "string") {
+    return {
+      name: entry.name,
+      scaffold: entry.scaffold !== false,
+      selection: { packs: entry.packs, excludePacks: entry.excludePacks, skills: entry.skills },
+    };
+  }
+  throw new Error('Invalid projects entry in stackfit.local.json; use a string name or { "name": "...", "packs": [] }');
+}
+
+function resolveNamedProjects(roots, entries) {
+  return entries.map(normalizeProjectEntry).map((entry) => {
+    const matches = roots.map((root) => resolve(root, entry.name)).filter((path) => existsSync(resolve(path, ".git")));
+    if (!matches.length) {
+      throw new Error(
+        `Configured project '${entry.name}' not found under machine roots: ${roots.join(", ")}.`
+        + " Remove it from stackfit.local.json or add the folder that holds it to roots.",
+      );
+    }
+    if (matches.length > 1) throw new Error(`Configured project '${entry.name}' matches multiple roots: ${matches.join(", ")}`);
+    return { path: matches[0], scaffold: entry.scaffold, selection: entry.selection };
+  });
+}
+
+function lookupProjectEntry(catalog, projectPath) {
+  const fallback = { scaffold: true, selection: {} };
+  try {
+    const machine = resolveMachineProfile(loadJson(catalog.localPath, null));
+    const entry = machine?.projects?.map(normalizeProjectEntry).find((item) => item.name === basename(projectPath));
+    return entry ? { scaffold: entry.scaffold, selection: entry.selection } : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+const asTargets = (paths) => paths.map((path) => ({ path, scaffold: true, selection: {} }));
+
+export function selectedProjects(catalog, options) {
+  if (options.project) {
+    const path = resolve(options.project);
+    return { projects: [{ path, ...lookupProjectEntry(catalog, path) }] };
+  }
+  if (options.root) {
+    const roots = options.root.split(",").map((root) => expandHome(root));
+    const projects = [...new Set(roots.flatMap((root) => discoverProjects(root, catalog.root)))].sort();
+    if (!projects.length) throw new Error(`No Git repositories directly under ${roots.join(", ")}`);
+    return { projects: asTargets(projects) };
+  }
+  if (!options.all) throw new Error("Choose --project <path>, --root <dir>, or --all (this machine's stackfit.local.json)");
+  const machine = resolveMachineProfile(loadJson(catalog.localPath, null));
+  if (!machine) return { projects: asTargets(discoverProjects(dirname(catalog.root), catalog.root)) };
+  const roots = machine.roots.map((root) => expandHome(root, catalog.root));
+  const missing = roots.filter((root) => !existsSync(root));
+  if (missing.length) {
+    throw new Error(`Machine '${machine.id}' roots do not exist: ${missing.join(", ")}. Update stackfit.local.json for this machine.`);
+  }
+  const identity = currentMachineIdentity();
+  const resolvedMachine = { id: machine.id, platform: identity.platform, hostname: identity.hostname, roots };
+  const projects = machine.projects?.length
+    ? resolveNamedProjects(roots, machine.projects)
+    : asTargets([...new Set(roots.flatMap((root) => discoverProjects(root, catalog.root)))].sort());
+  return { projects, machine: resolvedMachine };
+}