@codewalla_india/openspec 1.3.1 → 1.3.2

package/dist/core/shared-skill-target.js

@@ -0,0 +1,156 @@
+import path from 'path';
+import * as fs from 'fs';
+import { AI_TOOLS, OPENSPEC_SKILL_NAMES } from './config.js';
+import { FileSystemUtils } from '../utils/file-system.js';
+const TARGET_MARKER = '.openspec-target';
+/** Returns the ownership-marker path for one shared skills root. */
+function markerPath(projectPath, skillsDir) {
+    return path.join(projectPath, skillsDir, 'skills', TARGET_MARKER);
+}
+/** Reads a valid-looking marker value without letting linked roots escape. */
+export function readSharedSkillTarget(projectPath, skillsDir) {
+    try {
+        const target = markerPath(projectPath, skillsDir);
+        FileSystemUtils.assertProjectArtifactPath(projectPath, target);
+        return fs.readFileSync(target, 'utf-8').trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether a tool still has an allowlisted managed skill under an old root. */
+function hasLegacySkills(projectPath, tool) {
+    return (tool.legacySkillsDirs ?? []).some((root) => {
+        const skillsDir = path.join(projectPath, root, 'skills');
+        return OPENSPEC_SKILL_NAMES.some((skillName) => {
+            try {
+                const skillFile = path.join(skillsDir, skillName, 'SKILL.md');
+                FileSystemUtils.assertProjectArtifactPath(projectPath, skillFile);
+                return fs.existsSync(skillFile);
+            }
+            catch {
+                return false;
+            }
+        });
+    });
+}
+/**
+ * Infers pre-marker ownership from generated invocation syntax. This preserves
+ * both existing generic `.agents` trees and Codex trees users moved manually.
+ */
+function inferSharedSkillTarget(projectPath, skillsDir) {
+    let foundGenericReference = false;
+    for (const skillName of OPENSPEC_SKILL_NAMES) {
+        const skillFile = path.join(projectPath, skillsDir, 'skills', skillName, 'SKILL.md');
+        try {
+            FileSystemUtils.assertProjectArtifactPath(projectPath, skillFile);
+            const content = fs.readFileSync(skillFile, 'utf-8');
+            if (content.includes('$openspec-'))
+                return 'codex';
+            if (content.includes('/openspec-'))
+                foundGenericReference = true;
+        }
+        catch {
+            // Missing, unreadable, or out-of-project files provide no ownership signal.
+        }
+    }
+    return foundGenericReference ? 'agents' : undefined;
+}
+/** Whether the canonical shared root already contains an OpenSpec skill. */
+function hasCurrentSkills(projectPath, skillsDir) {
+    return OPENSPEC_SKILL_NAMES.some((skillName) => {
+        const skillFile = path.join(projectPath, skillsDir, 'skills', skillName, 'SKILL.md');
+        try {
+            FileSystemUtils.assertProjectArtifactPath(projectPath, skillFile);
+            return fs.existsSync(skillFile);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * A shared skill root can only hold one rendered variant of each skill.
+ * Keep the writer recorded so later updates do not infer every tool that
+ * happens to use the same directory.
+ */
+export function reconcileSharedSkillTargets(projectPath, tools) {
+    const byRoot = new Map();
+    for (const tool of tools) {
+        if (!tool.skillsDir)
+            continue;
+        const group = byRoot.get(tool.skillsDir) ?? [];
+        group.push(tool);
+        byRoot.set(tool.skillsDir, group);
+    }
+    const reconciled = [];
+    for (const group of byRoot.values()) {
+        if (group.length === 1) {
+            reconciled.push(group[0]);
+            continue;
+        }
+        const root = group[0].skillsDir;
+        const marked = readSharedSkillTarget(projectPath, root);
+        const markedTool = group.find((tool) => tool.value === marked);
+        if (markedTool) {
+            reconciled.push(markedTool);
+            continue;
+        }
+        const inferred = inferSharedSkillTarget(projectPath, root);
+        const legacyCodex = group.find((tool) => tool.value === 'codex' && hasLegacySkills(projectPath, tool));
+        if (inferred === 'agents' && legacyCodex) {
+            // Before ownership markers existed, selecting both targets produced a
+            // generic canonical tree plus a Codex-only legacy tree. Codex now emits
+            // a dual-syntax canonical tree, so it can safely consolidate that state.
+            reconciled.push(legacyCodex);
+            continue;
+        }
+        const inferredTool = group.find((tool) => tool.value === inferred);
+        if (inferredTool) {
+            reconciled.push(inferredTool);
+            continue;
+        }
+        // An unmarked canonical tree predates Codex's move into `.agents`; keep
+        // that established agents target instead of overwriting it from `.codex`.
+        if (hasCurrentSkills(projectPath, root)) {
+            reconciled.push(group.find((tool) => tool.value === 'agents') ?? group[0]);
+            continue;
+        }
+        const legacyTool = group.find((tool) => hasLegacySkills(projectPath, tool));
+        if (legacyTool) {
+            reconciled.push(legacyTool);
+            continue;
+        }
+        // `.agents` existed as the vendor-neutral target before Codex adopted it.
+        // Unmarked trees therefore retain that established meaning.
+        reconciled.push(group.find((tool) => tool.value === 'agents') ?? group[0]);
+    }
+    return reconciled;
+}
+/**
+ * Returns whether a tool is the active writer for its physical skills root.
+ * Non-shared roots are always active.
+ */
+export function isSharedSkillTargetActive(projectPath, toolId) {
+    const tool = AI_TOOLS.find((candidate) => candidate.value === toolId);
+    if (!tool?.skillsDir)
+        return false;
+    const sharingRoot = AI_TOOLS.filter((candidate) => candidate.skillsDir === tool.skillsDir);
+    if (sharingRoot.length < 2)
+        return true;
+    return reconcileSharedSkillTargets(projectPath, sharingRoot)
+        .some((candidate) => candidate.value === toolId);
+}
+export function writeSharedSkillTarget(projectPath, toolId) {
+    const tool = AI_TOOLS.find((candidate) => candidate.value === toolId);
+    if (!tool?.skillsDir)
+        return;
+    const sharingRoot = AI_TOOLS.filter((candidate) => candidate.skillsDir === tool.skillsDir);
+    if (sharingRoot.length < 2)
+        return;
+    const target = markerPath(projectPath, tool.skillsDir);
+    FileSystemUtils.assertProjectArtifactPath(projectPath, target);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, `${toolId}\n`, 'utf-8');
+}
+//# sourceMappingURL=shared-skill-target.js.map

package/dist/core/specs-apply.d.ts

@@ -5,28 +5,16 @@
  * Applies delta specs from a change to main specs without archiving.
  */
 export interface SpecUpdate {
+    /** Capability id relative to the specs root, forward-slash separated (e.g. "web" or "platform/session-layout"). */
+    id: string;
+    /** Allowed root for the delta source. */
+    sourceRoot: string;
     source: string;
+    /** Allowed root for the main-spec target. */
+    targetRoot: string;
     target: string;
     exists: boolean;
 }
-export interface ApplyResult {
-    capability: string;
-    added: number;
-    modified: number;
-    removed: number;
-    renamed: number;
-}
-export interface SpecsApplyOutput {
-    changeName: string;
-    capabilities: ApplyResult[];
-    totals: {
-        added: number;
-        modified: number;
-        removed: number;
-        renamed: number;
-    };
-    noChanges: boolean;
-}
 /**
  * Find all delta spec files that need to be applied from a change.
  */
@@ -45,7 +33,75 @@ export declare function buildUpdatedSpec(update: SpecUpdate, changeName: string,
         removed: number;
         renamed: number;
     };
+    warnings: string[];
+    /**
+     * Every canonical `### Requirement:` block the delta could act on is gone.
+     * This is only a *candidate* signal for retirement (#1302): the validator, not
+     * this count, decides whether `rebuilt` is actually unwritable - it recognises
+     * requirement shapes this parser sweeps into the preamble, so a spec can be
+     * blockless here and still validate. See `isRetirableSpec` in archive.ts.
+     */
+    noRequirementBlocks: boolean;
+    /**
+     * Every non-blank line of the spec this merge cannot name.
+     *
+     * Retirement deletes the whole file, so the only safe question is whether the
+     * merge can account for all of it. `extractRequirementsSection` splits a spec
+     * into five slices, and auditing a subset is how this guard kept failing: for
+     * seven rounds it looked for requirement-SHAPED text and was beaten by a new
+     * disguise each time, and when it started asking where content landed it
+     * still read only the preamble and the tail - so content simply moved into a
+     * slice nobody checked, and authored prose sitting inside a removed block's
+     * raw was deleted while the report said only "Purpose" was lost.
+     *
+     * So this accounts for the whole file: the title, the `## Purpose` section,
+     * the `## Requirements` header, and, inside each requirement block, the parts
+     * that make up a requirement - its header, its statement, and its scenarios'
+     * bullets. Every other non-blank line is reported and refuses the retirement.
+     *
+     * Fails safe in every direction: a line this cannot classify counts as
+     * unaccounted, which refuses rather than deletes.
+     */
+    unaccountedContent: string[];
 }>;
+/**
+ * Retire a capability whose last requirement a delta removed: delete its main
+ * spec and prune any directories the deletion leaves empty. Returns false when
+ * there was nothing to delete.
+ *
+ * Gated by the caller on the change's `retire_capabilities` marker, so the one
+ * archive action that removes a file from `openspec/specs/` is always something
+ * the author asked for rather than something inferred from a delta's shape. The
+ * file is recoverable from git, which the report names; applying REMOVED already
+ * deletes requirement content from a main spec, so deleting the spec once
+ * nothing is left is the same operation carried to its end rather than a new
+ * kind of act.
+ *
+ * Only the generated `spec.md` is removed - a directory holding anything else (a
+ * nested capability, a hand-kept note) is left in place.
+ *
+ * The target must resolve inside the selected specs root. A capability-directory
+ * symlink must not turn a retirement marker into authorization to delete an
+ * unrelated external file. A symlinked `spec.md` itself is safe: unlink removes
+ * the link and leaves its target alone.
+ *
+ * Directory pruning IS bounded, by REAL paths rather than string prefixes:
+ * `path.resolve` collapses `..` but does not resolve symlinks, and `readdir` and
+ * `rmdir` both follow them, so a symlinked capability directory would otherwise
+ * let the walk delete directories outside the specs root entirely.
+ */
+export declare function retireSpec(update: SpecUpdate, mainSpecsDir: string, options?: {
+    silent?: boolean;
+    displayPath?: string;
+    beforeMutate?: () => Promise<void>;
+    verifyDisplaced?: (displacedPath: string) => Promise<void>;
+    deferDelete?: boolean;
+}): Promise<{
+    retired: boolean;
+    resolvedPath?: string;
+    displacedPath?: string;
+}>;
+export declare function finalizeRetiredSpec(target: string, displacedPath: string, mainSpecsDir: string): Promise<void>;
 /**
  * Write an updated spec to disk.
  */
@@ -57,22 +113,13 @@ export declare function writeUpdatedSpec(update: SpecUpdate, rebuilt: string, co
 }, options?: {
     silent?: boolean;
     displayPath?: string;
+    beforeMutate?: () => Promise<void>;
 }): Promise<void>;
 /**
- * Build a skeleton spec for new capabilities.
- */
-export declare function buildSpecSkeleton(specFolderName: string, changeName: string): string;
-/**
- * Apply all delta specs from a change to main specs.
- *
- * @param projectRoot - The project root directory
- * @param changeName - The name of the change to apply
- * @param options - Options for the operation
- * @returns Result of the operation with counts
+ * Build a skeleton spec for new capabilities. When the delta spec authored a
+ * `## Purpose`, carry it over instead of the TBD placeholder (#1413) - archive
+ * invents the Purpose for a brand-new main spec either way, and the author's
+ * own wording beats a placeholder they then have to hand-edit.
  */
-export declare function applySpecs(projectRoot: string, changeName: string, options?: {
-    dryRun?: boolean;
-    skipValidation?: boolean;
-    silent?: boolean;
-}): Promise<SpecsApplyOutput>;
+export declare function buildSpecSkeleton(specFolderName: string, changeName: string, purpose?: string): string;
 //# sourceMappingURL=specs-apply.d.ts.map