@opengsd/gsd-core 1.2.0 → 1.3.0

package/gsd-core/bin/lib/surface.cjs

@@ -0,0 +1,406 @@
+"use strict";
+/**
+ * Runtime surface module — ADR-0011 Phase 2 (Option B).
+ *
+ * Manages the runtime enable/disable surface state (the `.gsd-surface.json` marker in
+ * each runtime's config dir root (e.g., ~/.claude)) independently of the install-time profile marker
+ * (`.gsd-profile`). Runtime config locations are resolved by callers.
+ *
+ * Effective skill set = base profile ∪ explicitAdds − disabledClusters − explicitRemoves,
+ * then transitively closed via the manifest.
+ *
+ * Exports:
+ *   readSurface(runtimeConfigDir)
+ *   writeSurface(runtimeConfigDir, surfaceState)
+ *   resolveSurface(runtimeConfigDir, manifest, clusterMap)
+ *   applySurface(runtimeConfigDir, layout, manifest, clusterMap)
+ *   listSurface(runtimeConfigDir, manifest, clusterMap)
+ *   pruneSkillDirs(skillsDir, retainedNames, prefix, manifest)
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/surface.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const installProfiles = require("./install-profiles.cjs");
+const { readActiveProfile, resolveProfile, loadSkillsManifest, } = installProfiles;
+const clusters_cjs_1 = require("./clusters.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const runtimeArtifactLayout = require("./runtime-artifact-layout.cjs");
+const { findInstallSourceRoot } = runtimeArtifactLayout;
+const SURFACE_FILE_NAME = '.gsd-surface.json';
+/**
+ * Read the surface state from a runtime config directory.
+ *
+ * @param runtimeConfigDir
+ * @returns null if file missing or corrupt
+ */
+function readSurface(runtimeConfigDir) {
+    const filePath = node_path_1.default.join(runtimeConfigDir, SURFACE_FILE_NAME);
+    try {
+        const raw = node_fs_1.default.readFileSync(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        // Structural validation — must have these fields with expected types
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        const p = parsed;
+        if (typeof p['baseProfile'] !== 'string')
+            return null;
+        if (!Array.isArray(p['disabledClusters']))
+            return null;
+        if (!Array.isArray(p['explicitAdds']))
+            return null;
+        if (!Array.isArray(p['explicitRemoves']))
+            return null;
+        return {
+            baseProfile: p['baseProfile'],
+            disabledClusters: p['disabledClusters'],
+            explicitAdds: p['explicitAdds'],
+            explicitRemoves: p['explicitRemoves'],
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write the surface state atomically via the platform seam (mkdir + tmp+rename).
+ */
+function writeSurface(runtimeConfigDir, surfaceState) {
+    (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(runtimeConfigDir, SURFACE_FILE_NAME), JSON.stringify(surfaceState, null, 2) + '\n');
+}
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+/**
+ * Expand cluster names to skill stems using the provided clusterMap.
+ */
+function clustersToSkills(clusterNames, clusterMap) {
+    const result = new Set();
+    for (const name of clusterNames) {
+        const members = clusterMap[name];
+        if (members) {
+            for (const s of members)
+                result.add(s);
+        }
+    }
+    return result;
+}
+/**
+ * Normalize manifest inputs to the skill-dependency Map shape expected by
+ * resolveProfile/computeClosure.
+ *
+ * Supports:
+ *  - canonical Map<string, string[]>
+ *  - legacy plain object map: { [stem]: string[] }
+ *  - parsed gsd-file-manifest.json object ({ files: { ... } }) by rebuilding
+ *    the dependency manifest from the install source tree
+ */
+function normalizeSkillManifest(runtimeConfigDir, manifest) {
+    if (manifest instanceof Map) {
+        return manifest;
+    }
+    if (!manifest || typeof manifest !== 'object') {
+        return new Map();
+    }
+    // Legacy/ad-hoc object map: stem -> requires[]
+    const arrayEntries = Object.entries(manifest).filter(([, value]) => Array.isArray(value));
+    if (arrayEntries.length > 0) {
+        return new Map(arrayEntries.map(([stem, deps]) => [stem, deps]));
+    }
+    // Parsed gsd-file-manifest.json shape: rebuild the dependency map from source.
+    const manifestObj = manifest;
+    if (manifestObj['files'] && typeof manifestObj['files'] === 'object') {
+        const srcCommandsDir = findInstallSourceRoot(runtimeConfigDir);
+        return loadSkillsManifest(srcCommandsDir);
+    }
+    return new Map();
+}
+/**
+ * Resolve the effective surface to a typed profile-like object.
+ * Shape: { name, skills: Set<string>|'*', agents: Set<string> }
+ *
+ * Resolution order:
+ * 1. Start with base profile resolved via resolveProfile()
+ * 2. Remove skills in disabled clusters
+ * 3. Add explicitAdds (and their transitive closure)
+ * 4. Remove explicitRemoves (only the stem itself, no cascade)
+ */
+function resolveSurface(runtimeConfigDir, manifest, clusterMap) {
+    const cm = clusterMap || clusters_cjs_1.CLUSTERS;
+    const skillManifest = normalizeSkillManifest(runtimeConfigDir, manifest);
+    const surface = readSurface(runtimeConfigDir);
+    // Determine base profile name: from surface state or from .gsd-profile marker
+    const baseProfileName = (surface && surface.baseProfile)
+        ? surface.baseProfile
+        : (readActiveProfile(runtimeConfigDir) || 'full');
+    // Resolve base profile
+    const baseResolved = resolveProfile({
+        modes: baseProfileName.split(',').map((s) => s.trim()),
+        manifest: skillManifest,
+    });
+    // If full, we need to enumerate all skills from the manifest
+    let skills;
+    if (baseResolved.skills === '*') {
+        // Materialize all skill stems from manifest
+        skills = new Set();
+        for (const [key] of skillManifest) {
+            if (!key.startsWith('_calls_agents_'))
+                skills.add(key);
+        }
+    }
+    else {
+        skills = new Set(baseResolved.skills);
+    }
+    if (surface) {
+        // Step 2: remove disabled cluster members
+        const disabledSkills = clustersToSkills(surface.disabledClusters, cm);
+        for (const s of disabledSkills)
+            skills.delete(s);
+        // Step 3: add explicitAdds with transitive closure
+        if (surface.explicitAdds.length > 0) {
+            const addSet = new Set(surface.explicitAdds);
+            // Compute closure of adds
+            const queue = [...addSet];
+            const visited = new Set(addSet);
+            while (queue.length > 0) {
+                const stem = queue.pop();
+                const deps = skillManifest.get(stem) || [];
+                for (const dep of deps) {
+                    if (!visited.has(dep)) {
+                        visited.add(dep);
+                        queue.push(dep);
+                    }
+                }
+            }
+            for (const s of visited)
+                skills.add(s);
+        }
+        // Step 4: remove explicitRemoves (stem only, no cascade)
+        for (const s of surface.explicitRemoves) {
+            skills.delete(s);
+        }
+    }
+    // Derive agents from skills
+    const agents = new Set();
+    for (const skillStem of skills) {
+        const agentRefs = skillManifest.get(`_calls_agents_${skillStem}`) || [];
+        for (const agentStem of agentRefs)
+            agents.add(agentStem);
+    }
+    const name = surface ? `surface:${surface.baseProfile}` : `profile:${baseProfileName}`;
+    return { name, skills, agents };
+}
+// ---------------------------------------------------------------------------
+// Apply
+// ---------------------------------------------------------------------------
+/**
+ * Re-stage the active surface using the resolved layout.
+ * Iterates layout.kinds and syncs each artifact kind to its destination.
+ */
+function applySurface(runtimeConfigDir, layout, manifest, clusterMap) {
+    if (node_path_1.default.resolve(runtimeConfigDir) !== node_path_1.default.resolve(layout.configDir)) {
+        throw new TypeError('applySurface runtimeConfigDir must match layout.configDir');
+    }
+    const skillManifest = normalizeSkillManifest(layout.configDir, manifest);
+    const resolved = resolveSurface(layout.configDir, skillManifest, clusterMap);
+    for (const kind of layout.kinds) {
+        const staged = kind.stage(resolved);
+        const dest = node_path_1.default.join(layout.configDir, kind.destSubpath);
+        _syncGsdDir(staged, dest, kind, skillManifest);
+    }
+    return resolved;
+}
+/**
+ * Prune GSD-managed skill directories from a skills directory.
+ *
+ * Removes every directory in `skillsDir` that is GSD-owned but NOT listed
+ * in `retainedNames`. User-owned dirs (not matching the GSD ownership criteria)
+ * are always preserved.
+ *
+ * Ownership criteria:
+ *   - Non-empty prefix (e.g. 'gsd-'): dir name starts with that prefix AND
+ *     appears in the manifest (manifest membership is required). Dirs that match
+ *     the prefix but are NOT in the manifest are treated as user-owned and
+ *     preserved — this prevents data loss for user-created gsd-* directories.
+ *     A warning is written to stderr when such a dir is encountered.
+ *   - Empty prefix (Hermes): dir name appears as a canonical skill stem in the
+ *     manifest. User dirs not in the manifest are preserved.
+ *   - Empty prefix without manifest, or manifest not a Map: conservative; no
+ *     dirs are removed.
+ *
+ * This is the single point of truth for skill-dir pruning. Both _syncGsdDir
+ * (surface apply) and callers that need stand-alone pruning use this function.
+ *
+ * @param skillsDir        directory that contains the gsd-STEM sub-dirs
+ * @param retainedNames    set of directory names to keep (e.g. 'gsd-help')
+ * @param prefix           GSD dir prefix, e.g. 'gsd-' (or '' for Hermes)
+ * @param manifest         optional; required for Hermes empty-prefix case
+ *                         and for manifest-membership gate in prefixed case.
+ *                         Must be a Map; any other type is treated as missing.
+ */
+function pruneSkillDirs(skillsDir, retainedNames, prefix, manifest) {
+    if (!node_fs_1.default.existsSync(skillsDir))
+        return;
+    // Finding 2: guard against callers passing a truthy non-Map as manifest.
+    // A non-Map manifest would throw on .keys(); treat it as absent and be conservative.
+    const safeManifest = (manifest instanceof Map) ? manifest : null;
+    // Build the canonical stem set from the manifest (used for both prefixed and Hermes paths).
+    // Deletion requires manifest membership — without a valid manifest, be conservative.
+    const canonicalStems = safeManifest
+        ? new Set([...safeManifest.keys()].filter(k => !k.startsWith('_calls_agents_')))
+        : null;
+    for (const entry of node_fs_1.default.readdirSync(skillsDir)) {
+        const entryPath = node_path_1.default.join(skillsDir, entry);
+        if (!node_fs_1.default.statSync(entryPath).isDirectory())
+            continue;
+        let isGsdOwned;
+        if (prefix !== '') {
+            if (!entry.startsWith(prefix)) {
+                // Does not match prefix at all — user-owned, preserve.
+                continue;
+            }
+            if (!canonicalStems) {
+                // No manifest available: cannot confirm ownership — preserve conservatively.
+                continue;
+            }
+            // Finding 1 fix: prefix match is necessary but NOT sufficient.
+            // The dir must also be in the manifest to be considered GSD-owned.
+            // A user-created gsd-* dir that isn't in the manifest is preserved with a warning.
+            if (!canonicalStems.has(entry.slice(prefix.length))) {
+                process.stderr.write(`[gsd] Warning: ${entry} matches GSD prefix '${prefix}' but is not in the manifest — preserving (user-owned or unknown)\n`);
+                continue;
+            }
+            isGsdOwned = true;
+        }
+        else if (canonicalStems) {
+            // Hermes: GSD-owned iff the directory name appears in the canonical manifest.
+            isGsdOwned = canonicalStems.has(entry);
+        }
+        else {
+            // No manifest available: be conservative, don't remove anything.
+            continue;
+        }
+        if (!isGsdOwned)
+            continue; // Hermes path only: preserve user-owned dirs not in manifest
+        if (retainedNames.has(entry))
+            continue; // GSD-owned and in retain set
+        try {
+            node_fs_1.default.rmSync(entryPath, { recursive: true, force: true });
+        }
+        catch (err) {
+            process.stderr.write(`surface: failed to prune ${entryPath}: ${err.message}\n`);
+        }
+    }
+}
+/**
+ * Sync destination directory from staged source.
+ *
+ * For 'commands' kind: iterate *.md files in destDir, remove if not in staged set.
+ * For 'agents' kind: same, but only remove files starting with 'gsd-' prefix.
+ * For 'skills' kind: iterate directories in destDir matching kind.prefix; add missing
+ *   by copying recursively; remove dirs not in staged set. Preserves dirs not matching
+ *   the prefix (user-owned skills). Pruning is delegated to pruneSkillDirs().
+ *
+ * For Hermes (empty prefix): uses manifest membership to discriminate GSD-owned vs
+ * user-owned dirs. GSD-owned = stem in manifest; removal targets = in manifest AND
+ * not in staged set. User-owned (not in manifest) are always preserved.
+ */
+function _syncGsdDir(stagedDir, destDir, kind, manifest) {
+    if (!node_fs_1.default.existsSync(stagedDir))
+        return;
+    node_fs_1.default.mkdirSync(destDir, { recursive: true });
+    // Normalize: allow legacy string context for backward-compat with internal callers
+    const kindName = (typeof kind === 'string') ? kind : kind.kind;
+    const kindPrefix = (typeof kind === 'object' && kind !== null) ? kind.prefix : 'gsd-';
+    if (kindName === 'skills') {
+        // Skills kind: work with directories, not files.
+        // Each staged entry is a directory named ${prefix}${stem}.
+        const stagedDirs = new Set(node_fs_1.default.readdirSync(stagedDir).filter(entry => {
+            return node_fs_1.default.statSync(node_path_1.default.join(stagedDir, entry)).isDirectory();
+        }));
+        // Copy missing dirs from staged to dest (always overwrite to ensure content is current)
+        for (const dirName of stagedDirs) {
+            const destSubDir = node_path_1.default.join(destDir, dirName);
+            node_fs_1.default.cpSync(node_path_1.default.join(stagedDir, dirName), destSubDir, { recursive: true });
+        }
+        // Prune GSD-owned dirs that are no longer in the staged set.
+        // pruneSkillDirs() is the single point of truth for this logic.
+        pruneSkillDirs(destDir, stagedDirs, kindPrefix, manifest);
+    }
+    else {
+        // commands / agents kind: work with .md files
+        const stagedFiles = new Set(node_fs_1.default.readdirSync(stagedDir).filter(f => f.endsWith('.md')));
+        // Copy files from staged to dest (overwrite to keep content current)
+        for (const file of stagedFiles) {
+            node_fs_1.default.copyFileSync(node_path_1.default.join(stagedDir, file), node_path_1.default.join(destDir, file));
+        }
+        // Remove gsd-only files from dest that aren't in staged set
+        // For commands dir: all .md files are gsd skills
+        // For agents dir: only gsd-* files
+        const destEntries = node_fs_1.default.readdirSync(destDir).filter(f => f.endsWith('.md'));
+        for (const file of destEntries) {
+            if (kindName === 'agents' && !file.startsWith('gsd-'))
+                continue;
+            if (!stagedFiles.has(file)) {
+                try {
+                    node_fs_1.default.unlinkSync(node_path_1.default.join(destDir, file));
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// List
+// ---------------------------------------------------------------------------
+/**
+ * List the currently enabled and disabled skills with token cost.
+ *
+ * Token cost = sum of description lengths ÷ 4 (mirrors audit script).
+ * Descriptions are read from the install source (findInstallSourceRoot).
+ */
+function listSurface(runtimeConfigDir, manifest, clusterMap) {
+    const skillManifest = normalizeSkillManifest(runtimeConfigDir, manifest);
+    const resolved = resolveSurface(runtimeConfigDir, skillManifest, clusterMap);
+    // All known stems from manifest (exclude _calls_agents_ meta keys)
+    const allStems = [];
+    for (const [key] of skillManifest) {
+        if (!key.startsWith('_calls_agents_'))
+            allStems.push(key);
+    }
+    const enabledSet = resolved.skills instanceof Set ? resolved.skills : new Set(allStems);
+    const enabled = allStems.filter(s => enabledSet.has(s)).sort();
+    const disabled = allStems.filter(s => !enabledSet.has(s)).sort();
+    // Compute token cost by reading descriptions from the install source
+    const srcCommandsDir = findInstallSourceRoot(runtimeConfigDir);
+    let tokenCost = 0;
+    for (const stem of enabled) {
+        const filePath = node_path_1.default.join(srcCommandsDir, `${stem}.md`);
+        try {
+            const content = node_fs_1.default.readFileSync(filePath, 'utf8');
+            const descMatch = content.match(/^description:\s*(.+)$/m);
+            if (descMatch) {
+                tokenCost += Math.ceil(descMatch[1].trim().length / 4);
+            }
+        }
+        catch { /* ignore */ }
+    }
+    return { enabled, disabled, tokenCost };
+}
+module.exports = {
+    readSurface,
+    writeSurface,
+    resolveSurface,
+    applySurface,
+    listSurface,
+    // Exported for testing and for callers that need stand-alone pruning
+    pruneSkillDirs,
+    _syncGsdDir,
+};

package/gsd-core/bin/lib/task-command-router.cjs

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Task command router — is-behavior-adding subcommand handler.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/task-command-router.cjs
+ * collapsed to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const core = require("./core.cjs");
+const { output, error, ERROR_REASON } = core;
+// ─── Implementation ───────────────────────────────────────────────────────────
+function isBehaviorAddingTaskContent(content) {
+    const tddTrue = /\btdd\s*=\s*["']true["']/i.test(content);
+    const behaviorMatch = content.match(/<behavior>([\s\S]*?)<\/behavior>/i);
+    const hasBehaviorBlock = Boolean(behaviorMatch && behaviorMatch[1].trim().length > 0);
+    const filesMatch = content.match(/<files>([\s\S]*?)<\/files>/i);
+    let hasSourceFiles = false;
+    if (filesMatch) {
+        const fileLines = filesMatch[1]
+            .split(/[\n,]/)
+            .map((line) => line.trim().replace(/^[-*]\s*/, ''))
+            .filter(Boolean);
+        hasSourceFiles = fileLines.some((file) => !/\.md$/i.test(file) &&
+            !/\.json$/i.test(file) &&
+            !/\.test\.[^.]+$/i.test(file) &&
+            !/\.spec\.[^.]+$/i.test(file) &&
+            !/(^|[\\/])tests?[\\/]/i.test(file) &&
+            !/\.(yml|yaml|toml|ini|cfg|conf|properties)$/i.test(file) &&
+            !/(^|[\\/])\.env(\..+)?$/i.test(file));
+    }
+    const isBehaviorAdding = tddTrue && hasBehaviorBlock && hasSourceFiles;
+    const missing = [];
+    if (!tddTrue)
+        missing.push('tdd="true" frontmatter absent');
+    if (!hasBehaviorBlock)
+        missing.push('<behavior> block missing or empty');
+    if (!hasSourceFiles)
+        missing.push('<files> has no non-test source file');
+    return {
+        is_behavior_adding: isBehaviorAdding,
+        checks: {
+            tdd_true: tddTrue,
+            has_behavior_block: hasBehaviorBlock,
+            has_source_files: hasSourceFiles,
+        },
+        reason: isBehaviorAdding ? null : `Not behavior-adding: ${missing.join('; ')}`,
+    };
+}
+function routeTaskCommand({ args, cwd, raw }) {
+    const subcommand = args[1];
+    if (subcommand !== 'is-behavior-adding') {
+        error('Unknown task subcommand. Available: is-behavior-adding', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    }
+    let content = null;
+    if (args[2] === '--task-content') {
+        content = args[3] || null;
+    }
+    else if (args[2]) {
+        const projectRoot = node_path_1.default.resolve(cwd || process.cwd());
+        const requestedPath = args[2];
+        const resolvedTaskPath = node_path_1.default.resolve(projectRoot, requestedPath);
+        const rel = node_path_1.default.relative(projectRoot, resolvedTaskPath);
+        if (rel === '..' || rel.startsWith(`..${node_path_1.default.sep}`)) {
+            error(`Task file is outside project scope: ${requestedPath}`, ERROR_REASON.USAGE);
+        }
+        if (!node_fs_1.default.existsSync(resolvedTaskPath)) {
+            error(`Task file not found: ${requestedPath}`, ERROR_REASON.USAGE);
+        }
+        content = node_fs_1.default.readFileSync(resolvedTaskPath, 'utf-8');
+    }
+    if (!content) {
+        error('Usage: task.is-behavior-adding <plan-file-path> | --task-content "<xml>"', ERROR_REASON.USAGE);
+    }
+    output(isBehaviorAddingTaskContent(content), raw, undefined);
+}
+module.exports = {
+    isBehaviorAddingTaskContent,
+    routeTaskCommand,
+};