@fission-ai/openspec 1.14.3 → 1.16.0

package/dist/commands/workflow/status.js

@@ -3,7 +3,6 @@
  *
  * Displays artifact completion status for a change.
  */
-import ora from 'ora';
 import chalk from 'chalk';
 import { getChangeDir } from '../../core/planning-home.js';
 import { resolveRootForCommand, toPlanningHome, toRootOutput, withStoreFlag, isStoreSelectedRoot, findDeclaringProjectRoot, } from '../../core/root-selection.js';
@@ -33,7 +32,11 @@ export async function statusCommand(options) {
     if (!root) {
         return;
     }
-    const spinner = options.json ? undefined : ora('Loading change status...').start();
+    let spinner;
+    if (!options.json) {
+        const { default: ora } = await import('ora');
+        spinner = ora('Loading change status...').start();
+    }
     try {
         const planningHome = toPlanningHome(root);
         const projectRoot = root.path;

package/dist/commands/workflow/templates.js

@@ -3,7 +3,6 @@
  *
  * Shows resolved template paths for all artifacts in a schema.
  */
-import ora from 'ora';
 import path from 'path';
 import { resolveSchema, getSchemaDir, ArtifactGraph, } from '../../core/artifact-graph/index.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
@@ -12,7 +11,11 @@ import { validateSchemaExists, DEFAULT_SCHEMA } from './shared.js';
 // Command Implementation
 // -----------------------------------------------------------------------------
 export async function templatesCommand(options) {
-    const spinner = options.json ? undefined : ora('Loading templates...').start();
+    let spinner;
+    if (!options.json) {
+        const { default: ora } = await import('ora');
+        spinner = ora('Loading templates...').start();
+    }
     try {
         const projectRoot = process.cwd();
         const schemaName = validateSchemaExists(options.schema ?? DEFAULT_SCHEMA, projectRoot);

package/dist/core/artifact-graph/resolver.d.ts

@@ -8,6 +8,12 @@ export declare class SchemaLoadError extends Error {
     readonly cause?: Error | undefined;
     constructor(message: string, schemaPath: string, cause?: Error | undefined);
 }
+/**
+ * Points the built-in schemas at another directory. The standalone binary has
+ * no package directory on disk, so it passes a function that extracts its
+ * embedded schemas; it runs only when a command first needs them.
+ */
+export declare function setPackageSchemasDir(resolveDir: () => string): void;
 /**
  * Gets the package's built-in schemas directory path.
  * Uses import.meta.url to resolve relative to the current module.

package/dist/core/artifact-graph/resolver.js

@@ -17,11 +17,22 @@ export class SchemaLoadError extends Error {
         this.name = 'SchemaLoadError';
     }
 }
+let packageSchemasDirOverride;
+/**
+ * Points the built-in schemas at another directory. The standalone binary has
+ * no package directory on disk, so it passes a function that extracts its
+ * embedded schemas; it runs only when a command first needs them.
+ */
+export function setPackageSchemasDir(resolveDir) {
+    packageSchemasDirOverride = resolveDir;
+}
 /**
  * Gets the package's built-in schemas directory path.
  * Uses import.meta.url to resolve relative to the current module.
  */
 export function getPackageSchemasDir() {
+    if (packageSchemasDirOverride)
+        return packageSchemasDirOverride();
     const currentFile = fileURLToPath(import.meta.url);
     // Navigate from dist/core/artifact-graph/ to package root's schemas/
     return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');

package/dist/core/available-tools.d.ts

@@ -5,6 +5,7 @@
  * for their configuration directories.
  */
 import { type AIToolOption } from './config.js';
+import { type FileView } from './file-view.js';
 /**
  * Scans the project path for AI tool configuration directories and returns
  * the tools that are present.
@@ -13,5 +14,5 @@ import { type AIToolOption } from './config.js';
  * directories). Otherwise checks the project's `skillsDir`, or managed skill
  * files in the user's home directory for a global skill target.
  */
-export declare function getAvailableTools(projectPath: string): AIToolOption[];
+export declare function getAvailableTools(projectPath: string, view?: FileView): AIToolOption[];
 //# sourceMappingURL=available-tools.d.ts.map

package/dist/core/available-tools.js

@@ -5,11 +5,11 @@
  * for their configuration directories.
  */
 import path from 'path';
-import * as fs from 'fs';
 import { AI_TOOLS } from './config.js';
 import { reconcileSharedSkillTargets } from './shared-skill-target.js';
 import { SKILL_NAMES } from './shared/tool-detection.js';
 import { resolveToolSkillsDir, toolSupportsSkills } from './shared/skill-paths.js';
+import { DISK_VIEW } from './file-view.js';
 /**
  * Scans the project path for AI tool configuration directories and returns
  * the tools that are present.
@@ -18,49 +18,29 @@ import { resolveToolSkillsDir, toolSupportsSkills } from './shared/skill-paths.j
  * directories). Otherwise checks the project's `skillsDir`, or managed skill
  * files in the user's home directory for a global skill target.
  */
-export function getAvailableTools(projectPath) {
+export function getAvailableTools(projectPath, view = DISK_VIEW) {
     const available = AI_TOOLS.filter((tool) => {
         if (!toolSupportsSkills(tool))
             return false;
         if (tool.globalSkillsDir) {
             const skillsDir = resolveToolSkillsDir(projectPath, tool);
-            return SKILL_NAMES.some((skillName) => fs.existsSync(path.join(skillsDir, skillName, 'SKILL.md')));
+            return SKILL_NAMES.some((skillName) => view.exists(path.join(skillsDir, skillName, 'SKILL.md')));
         }
         if (!tool.skillsDir)
             return false;
         if (tool.detectionPaths && tool.detectionPaths.length > 0) {
-            // statSync without .isDirectory() — detection paths can be files or directories
-            return tool.detectionPaths.some((p) => {
-                try {
-                    fs.statSync(path.join(projectPath, p));
-                    return true;
-                }
-                catch {
-                    return false;
-                }
-            });
-        }
-        const dirPath = path.join(projectPath, tool.skillsDir);
-        try {
-            return fs.statSync(dirPath).isDirectory();
-        }
-        catch {
-            return false;
+            // Presence, not type — detection paths can be files or directories
+            return tool.detectionPaths.some((p) => view.exists(path.join(projectPath, p)));
         }
+        return view.isDirectory(path.join(projectPath, tool.skillsDir));
     });
-    const activeProjectTools = new Set(reconcileSharedSkillTargets(projectPath, available.filter((tool) => tool.skillsDir)).map((tool) => tool.value));
+    const activeProjectTools = new Set(reconcileSharedSkillTargets(projectPath, available.filter((tool) => tool.skillsDir), view).map((tool) => tool.value));
     const hasIndependentDetectionPath = (tool) => (tool.detectionPaths ?? []).some((detectionPath) => {
         // Skill roots still go through managed-content reconciliation below;
         // their mere existence is not an independent tool signal.
         if (detectionPath.endsWith('/skills'))
             return false;
-        try {
-            fs.statSync(path.join(projectPath, detectionPath));
-            return true;
-        }
-        catch {
-            return false;
-        }
+        return view.exists(path.join(projectPath, detectionPath));
     });
     return available.filter((tool) => tool.globalSkillsDir ||
         hasIndependentDetectionPath(tool) ||

package/dist/core/completion-tip.d.ts

@@ -7,6 +7,29 @@ export interface CompletionTipOptions {
      */
     silent?: boolean;
 }
+/**
+ * Read the global config exactly as it sits on disk.
+ *
+ * Deliberately NOT `getGlobalConfig()`: that merges in defaults, and writing the
+ * merged result back would stamp `profile`/`delivery` into a file the user never
+ * set them in. `migrateIfNeeded` treats a raw `profile` as "already migrated",
+ * so that stamp would permanently suppress the one-time profile migration and
+ * cost users their installed workflow skills.
+ *
+ * Returns null when the file exists but cannot be read or parsed — a config we
+ * cannot understand is left strictly alone rather than overwritten.
+ */
+export declare function readRawConfig(): Record<string, unknown> | null;
+/**
+ * Record the flag, re-reading the config first and replacing the file by rename.
+ *
+ * Deciding whether to show the tip costs a `ps` spawn and a stat, and a sibling
+ * `openspec` process can write the same file in that window — on a first run
+ * that is exactly when telemetry mints `anonymousId`. Re-reading here keeps the
+ * write down to this one key, and the rename keeps a reader from ever seeing a
+ * half-written config.
+ */
+export declare function markConfigFlag(key: string): Promise<void>;
 /**
  * Print the completion tip once, the first time the CLI runs.
  * Never throws — a hint must not break a command.

package/dist/core/completion-tip.js

@@ -76,7 +76,7 @@ async function decideTip() {
  * Returns null when the file exists but cannot be read or parsed — a config we
  * cannot understand is left strictly alone rather than overwritten.
  */
-function readRawConfig() {
+export function readRawConfig() {
     const configPath = getGlobalConfigPath();
     if (!fs.existsSync(configPath)) {
         return {};
@@ -96,13 +96,13 @@ function readRawConfig() {
  * write down to this one key, and the rename keeps a reader from ever seeing a
  * half-written config.
  */
-async function markTipSeen() {
+export async function markConfigFlag(key) {
     const configPath = getGlobalConfigPath();
     const current = readRawConfig() ?? {};
     // The shared atomic writer: randomized temp name, owner-only mode, temp file
     // removed on failure. A predictable `<config>.<pid>.tmp` at the default mode
     // is both guessable and world-readable once renamed over the config.
-    await writeFileAtomically(configPath, JSON.stringify({ ...current, completionTipSeen: true }, null, 2) + '\n');
+    await writeFileAtomically(configPath, JSON.stringify({ ...current, [key]: true }, null, 2) + '\n');
 }
 /**
  * Print the completion tip once, the first time the CLI runs.
@@ -123,7 +123,7 @@ export async function maybeShowCompletionTip(options = {}) {
         const decision = await decideTip();
         // Record before printing: if the flag cannot be persisted, staying quiet
         // beats reprinting the tip on every future run.
-        await markTipSeen();
+        await markConfigFlag('completionTipSeen');
         if (decision === 'show') {
             console.error(`\n${COMPLETION_TIP_MESSAGE}`);
         }

package/dist/core/completions/command-registry.js

@@ -52,8 +52,23 @@ export const COMMAND_REGISTRY = [
                 name: 'force',
                 description: 'Force update even when tools are up to date',
             },
+            {
+                name: 'dry-run',
+                description: 'Report what the update would change without writing anything',
+            },
+            {
+                name: 'json',
+                description: 'With --dry-run, print the planned changes as JSON',
+            },
         ],
     },
+    {
+        name: 'install',
+        description: 'Install the standalone openspec, which runs without Node.js (latest release unless [version] is given)',
+        acceptsPositional: true,
+        positionals: [{ name: 'version', optional: true }],
+        flags: [],
+    },
     {
         name: 'version',
         description: 'Report the installed OpenSpec version and update availability',

package/dist/core/completions/installers/zsh-installer.d.ts

@@ -1,4 +1,6 @@
 import { InstallationResult } from '../factory.js';
+/** The .zshrc zsh will read, as shown to the user: `~/.zshrc` unless ZDOTDIR moves it. */
+export declare function zshrcDisplayPath(homeDir?: string): string;
 /**
  * Installer for Zsh completion scripts.
  * Supports both Oh My Zsh and standard Zsh configurations.
@@ -47,6 +49,11 @@ export declare class ZshInstaller {
      * @returns Path to .zshrc
      */
     private getZshrcPath;
+    /**
+     * Every .zshrc that may hold an OpenSpec block: the one zsh reads, plus
+     * ~/.zshrc, where installs before #2138 wrote it even under ZDOTDIR.
+     */
+    private getZshrcCandidates;
     /**
      * Generate .zshrc configuration content
      *
@@ -72,9 +79,10 @@ export declare class ZshInstaller {
      * Remove .zshrc configuration
      * Used during uninstallation
      *
+     * @param zshrcPath - The .zshrc to clean; defaults to the one zsh reads
      * @returns true if removed successfully, false otherwise
      */
-    removeZshrcConfig(): Promise<boolean>;
+    removeZshrcConfig(zshrcPath?: string): Promise<boolean>;
     /**
      * Install the completion script
      *

package/dist/core/completions/installers/zsh-installer.js

@@ -3,6 +3,23 @@ import path from 'path';
 import os from 'os';
 import { FileSystemUtils } from '../../../utils/file-system.js';
 import { shellSingleQuote } from './shell-quote.js';
+/**
+ * zsh reads its startup files from $ZDOTDIR when it is set, and from $HOME
+ * only otherwise, so a block written to ~/.zshrc under an XDG-style
+ * ZDOTDIR is never loaded (#2138).
+ */
+function zshrcDir(homeDir) {
+    const zdotdir = process.env.ZDOTDIR;
+    // zsh does not expand `~` in ZDOTDIR, and path.join would resolve a relative
+    // or `~/...` value against the current directory, writing a stray .zshrc
+    // into the user's project. Only an absolute ZDOTDIR moves the file.
+    return zdotdir && path.isAbsolute(zdotdir) ? zdotdir : homeDir;
+}
+/** The .zshrc zsh will read, as shown to the user: `~/.zshrc` unless ZDOTDIR moves it. */
+export function zshrcDisplayPath(homeDir = os.homedir()) {
+    const zshrcPath = path.join(zshrcDir(homeDir), '.zshrc');
+    return zshrcPath === path.join(homeDir, '.zshrc') ? '~/.zshrc' : zshrcPath;
+}
 /**
  * Installer for Zsh completion scripts.
  * Supports both Oh My Zsh and standard Zsh configurations.
@@ -99,7 +116,14 @@ export class ZshInstaller {
      * @returns Path to .zshrc
      */
     getZshrcPath() {
-        return path.join(this.homeDir, '.zshrc');
+        return path.join(zshrcDir(this.homeDir), '.zshrc');
+    }
+    /**
+     * Every .zshrc that may hold an OpenSpec block: the one zsh reads, plus
+     * ~/.zshrc, where installs before #2138 wrote it even under ZDOTDIR.
+     */
+    getZshrcCandidates() {
+        return [...new Set([this.getZshrcPath(), path.join(this.homeDir, '.zshrc')])];
     }
     /**
      * Generate .zshrc configuration content
@@ -150,9 +174,8 @@ export class ZshInstaller {
      *
      * @returns true if .zshrc exists and has markers
      */
-    async hasZshrcConfig() {
+    async hasZshrcConfig(zshrcPath = this.getZshrcPath()) {
         try {
-            const zshrcPath = this.getZshrcPath();
             const content = await fs.readFile(zshrcPath, 'utf-8');
             return content.includes(this.ZSHRC_MARKERS.start) && content.includes(this.ZSHRC_MARKERS.end);
         }
@@ -164,11 +187,11 @@ export class ZshInstaller {
      * Remove .zshrc configuration
      * Used during uninstallation
      *
+     * @param zshrcPath - The .zshrc to clean; defaults to the one zsh reads
      * @returns true if removed successfully, false otherwise
      */
-    async removeZshrcConfig() {
+    async removeZshrcConfig(zshrcPath = this.getZshrcPath()) {
         try {
-            const zshrcPath = this.getZshrcPath();
             // Check if file exists
             try {
                 await fs.access(zshrcPath);
@@ -224,16 +247,24 @@ export class ZshInstaller {
             try {
                 const existingContent = await fs.readFile(targetPath, 'utf-8');
                 if (existingContent === completionScript) {
-                    // Already installed and up to date
+                    // Already installed and up to date. Still make sure the .zshrc zsh
+                    // reads has the block: an install made before #2138 under ZDOTDIR
+                    // wrote it to ~/.zshrc, and re-running install is how that's fixed.
+                    const zshrcConfigured = isOhMyZsh
+                        ? false
+                        : await this.configureZshrc(path.dirname(targetPath));
                     return {
                         success: true,
                         installedPath: targetPath,
                         isOhMyZsh,
+                        zshrcConfigured,
                         message: 'Completion script is already installed (up to date)',
-                        instructions: [
-                            'The completion script is already installed and up to date.',
-                            'If completions are not working, try: exec zsh',
-                        ],
+                        instructions: isOhMyZsh || zshrcConfigured
+                            ? [
+                                'The completion script is already installed and up to date.',
+                                'If completions are not working, try: exec zsh',
+                            ]
+                            : this.generateInstructions(false, targetPath),
                     };
                 }
                 // File exists but content is different - this is an update
@@ -336,11 +367,11 @@ export class ZshInstaller {
         }
         else {
             const completionsDir = path.dirname(installedPath);
-            const zshrcPath = path.join(this.homeDir, '.zshrc');
+            const zshrcPath = this.getZshrcPath();
             return [
                 'Completion script installed to ~/.zsh/completions/',
                 '',
-                'To enable completions, add the following to your ~/.zshrc file:',
+                `To enable completions, add the following to your ${zshrcDisplayPath(this.homeDir)} file:`,
                 '',
                 `  # Add completions directory to fpath`,
                 `  fpath=(${shellSingleQuote(completionsDir)} $fpath)`,
@@ -375,11 +406,19 @@ export class ZshInstaller {
             }
             // Try to remove .zshrc configuration (only for standard Zsh)
             let zshrcWasPresent = false;
-            let zshrcCleaned = false;
+            const cleanedZshrcs = [];
+            const failedZshrcs = [];
             if (!isOhMyZsh) {
-                zshrcWasPresent = await this.hasZshrcConfig();
-                if (zshrcWasPresent) {
-                    zshrcCleaned = await this.removeZshrcConfig();
+                for (const zshrcPath of this.getZshrcCandidates()) {
+                    if (await this.hasZshrcConfig(zshrcPath)) {
+                        zshrcWasPresent = true;
+                        if (await this.removeZshrcConfig(zshrcPath)) {
+                            cleanedZshrcs.push(zshrcPath);
+                        }
+                        else {
+                            failedZshrcs.push(zshrcPath);
+                        }
+                    }
                 }
             }
             if (!scriptRemoved && !zshrcWasPresent) {
@@ -392,11 +431,17 @@ export class ZshInstaller {
             if (scriptRemoved) {
                 messages.push(`Completion script removed from ${targetPath}`);
             }
-            if (zshrcCleaned && !isOhMyZsh) {
-                messages.push('Removed OpenSpec configuration from ~/.zshrc');
+            const label = (zshrcPath) => zshrcPath === path.join(this.homeDir, '.zshrc') ? '~/.zshrc' : zshrcPath;
+            for (const zshrcPath of cleanedZshrcs) {
+                messages.push(`Removed OpenSpec configuration from ${label(zshrcPath)}`);
+            }
+            // A block left behind keeps loading the completions, so say so instead
+            // of reporting a clean uninstall.
+            for (const zshrcPath of failedZshrcs) {
+                messages.push(`Could not remove the OpenSpec block from ${label(zshrcPath)}; delete the lines between # OPENSPEC:START and # OPENSPEC:END by hand`);
             }
             return {
-                success: true,
+                success: failedZshrcs.length === 0,
                 message: messages.join('. '),
             };
         }

package/dist/core/config-schema.d.ts

@@ -20,6 +20,7 @@ export declare const GlobalConfigSchema: z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
     completionTipSeen: z.ZodOptional<z.ZodBoolean>;
+    standaloneTipSeen: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$loose>;
 export type GlobalConfigType = z.infer<typeof GlobalConfigSchema>;
 /**

package/dist/core/config-schema.js

@@ -34,6 +34,7 @@ export const GlobalConfigSchema = z
         .optional(),
     // Runtime-managed (like telemetry.noticeSeen); not user-settable via CLI set.
     completionTipSeen: z.boolean().optional(),
+    standaloneTipSeen: z.boolean().optional(),
 })
     .passthrough();
 /**

package/dist/core/file-view.d.ts

@@ -0,0 +1,13 @@
+/**
+ * How a check reads the files it inspects. Normally the disk. `update
+ * --dry-run` passes the tree as it has planned it, so a step that reads what
+ * an earlier step wrote sees the same thing it would in a real update.
+ */
+export interface FileView {
+    exists(filePath: string): boolean;
+    /** Throws, like `fs.readFileSync`, when the file is absent. */
+    read(filePath: string): string;
+    isDirectory(filePath: string): boolean;
+}
+export declare const DISK_VIEW: FileView;
+//# sourceMappingURL=file-view.d.ts.map

package/dist/core/file-view.js

@@ -0,0 +1,14 @@
+import * as fs from 'fs';
+export const DISK_VIEW = {
+    exists: (filePath) => fs.existsSync(filePath),
+    read: (filePath) => fs.readFileSync(filePath, 'utf-8'),
+    isDirectory: (filePath) => {
+        try {
+            return fs.statSync(filePath).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    },
+};
+//# sourceMappingURL=file-view.js.map

package/dist/core/github-copilot/cloud-agent.d.ts

@@ -28,6 +28,14 @@ export declare const COPILOT_CLOUD_FILES: {
     readonly setupSteps: string;
     readonly agent: string;
 };
+/**
+ * Every change the cloud-file sync makes on disk. `update --dry-run` passes a
+ * recorder, so the plan comes from this same code rather than a description.
+ */
+export interface CopilotCloudFileOps {
+    writeFile(filePath: string, content: string): Promise<void>;
+    removeFile(filePath: string): Promise<void>;
+}
 /**
  * Reconcile Copilot cloud agent files in the project directory.
  * Creates missing files and refreshes recognized legacy generated files while
@@ -35,7 +43,7 @@ export declare const COPILOT_CLOUD_FILES: {
  *
  * @returns Object indicating which files were written.
  */
-export declare function writeCopilotCloudFiles(projectPath: string): Promise<{
+export declare function writeCopilotCloudFiles(projectPath: string, ops?: CopilotCloudFileOps): Promise<{
     setupStepsWritten: boolean;
     agentWritten: boolean;
 }>;
@@ -45,7 +53,7 @@ export declare function writeCopilotCloudFiles(projectPath: string): Promise<{
  *
  * @returns Number of files removed.
  */
-export declare function removeCopilotCloudFiles(projectPath: string): Promise<number>;
+export declare function removeCopilotCloudFiles(projectPath: string, ops?: CopilotCloudFileOps): Promise<number>;
 /**
  * Read the persisted opt-in for Copilot cloud-file generation.
  *

package/dist/core/github-copilot/cloud-agent.js

@@ -242,10 +242,14 @@ function isLegacyCopilotCloudFile(relPath, content) {
 function isManagedCopilotCloudFile(relPath, content) {
     return isCurrentCopilotCloudFile(relPath, content) || isLegacyCopilotCloudFile(relPath, content);
 }
-async function reconcileCopilotCloudFile(fullPath, relPath) {
+const DIRECT_CLOUD_FILE_OPS = {
+    writeFile: (filePath, content) => FileSystemUtils.writeFile(filePath, content),
+    removeFile: (filePath) => fs.unlink(filePath),
+};
+async function reconcileCopilotCloudFile(fullPath, relPath, ops) {
     const currentContent = COPILOT_CLOUD_FILE_CONTENTS[relPath];
     if (!(await FileSystemUtils.fileExists(fullPath))) {
-        await FileSystemUtils.writeFile(fullPath, currentContent);
+        await ops.writeFile(fullPath, currentContent);
         return true;
     }
     const existingContent = await FileSystemUtils.readFile(fullPath);
@@ -255,7 +259,7 @@ async function reconcileCopilotCloudFile(fullPath, relPath) {
     if (!isLegacyCopilotCloudFile(relPath, existingContent)) {
         return false;
     }
-    await FileSystemUtils.writeFile(fullPath, currentContent);
+    await ops.writeFile(fullPath, currentContent);
     return true;
 }
 async function assertCreatableFilePath(filePath) {
@@ -313,7 +317,7 @@ async function classifyCopilotAgentReconciliation(agentPath, alternateAgentPath)
  *
  * @returns Object indicating which files were written.
  */
-export async function writeCopilotCloudFiles(projectPath) {
+export async function writeCopilotCloudFiles(projectPath, ops = DIRECT_CLOUD_FILE_OPS) {
     const setupStepsPath = FileSystemUtils.resolveProjectArtifactPath(projectPath, COPILOT_CLOUD_FILES.setupSteps);
     const agentPath = FileSystemUtils.resolveProjectArtifactPath(projectPath, COPILOT_CLOUD_FILES.agent);
     const alternateAgentPath = FileSystemUtils.resolveProjectArtifactPath(projectPath, COPILOT_AGENT_ALTERNATE_FILE);
@@ -323,13 +327,13 @@ export async function writeCopilotCloudFiles(projectPath) {
     await assertMissingOrRegularFile(agentPath);
     await assertMissingOrRegularFile(alternateAgentPath);
     const agentReconciliation = await classifyCopilotAgentReconciliation(agentPath, alternateAgentPath);
-    const setupStepsWritten = await reconcileCopilotCloudFile(setupStepsPath, COPILOT_CLOUD_FILES.setupSteps);
+    const setupStepsWritten = await reconcileCopilotCloudFile(setupStepsPath, COPILOT_CLOUD_FILES.setupSteps, ops);
     let agentWritten = false;
     if (agentReconciliation === 'reconcile') {
-        agentWritten = await reconcileCopilotCloudFile(agentPath, COPILOT_CLOUD_FILES.agent);
+        agentWritten = await reconcileCopilotCloudFile(agentPath, COPILOT_CLOUD_FILES.agent, ops);
     }
     else if (agentReconciliation === 'remove-managed') {
-        await fs.unlink(agentPath);
+        await ops.removeFile(agentPath);
     }
     return { setupStepsWritten, agentWritten };
 }
@@ -339,7 +343,7 @@ export async function writeCopilotCloudFiles(projectPath) {
  *
  * @returns Number of files removed.
  */
-export async function removeCopilotCloudFiles(projectPath) {
+export async function removeCopilotCloudFiles(projectPath, ops = DIRECT_CLOUD_FILE_OPS) {
     let removed = 0;
     const managedPaths = Object.values(COPILOT_CLOUD_FILES).map((relPath) => ({
         relPath,
@@ -354,7 +358,7 @@ export async function removeCopilotCloudFiles(projectPath) {
             if (!isManagedCopilotCloudFile(relPath, content)) {
                 continue;
             }
-            await fs.unlink(fullPath);
+            await ops.removeFile(fullPath);
             removed++;
         }
     }

package/dist/core/global-config.d.ts

@@ -28,6 +28,8 @@ export interface GlobalConfig {
     telemetry?: TelemetryConfig;
     /** Whether the first-run shell-completions tip has been shown. */
     completionTipSeen?: boolean;
+    /** Whether the one-time note about the standalone install has been shown. */
+    standaloneTipSeen?: boolean;
 }
 /**
  * Gets the global configuration directory path following XDG Base Directory Specification.
@@ -94,4 +96,6 @@ export interface SaveGlobalConfigOptions {
  * existing file it cannot parse unless `replaceUnreadable` is set.
  */
 export declare function saveGlobalConfig(config: GlobalConfig, options?: SaveGlobalConfigOptions): void;
+/** The bytes `saveGlobalConfig` writes, for a caller that only plans the write. */
+export declare function serializeGlobalConfig(config: GlobalConfig): string;
 //# sourceMappingURL=global-config.d.ts.map

package/dist/core/global-config.js

@@ -173,6 +173,10 @@ export function saveGlobalConfig(config, options = {}) {
     if (!fs.existsSync(configDir)) {
         fs.mkdirSync(configDir, { recursive: true });
     }
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    fs.writeFileSync(configPath, serializeGlobalConfig(config), 'utf-8');
+}
+/** The bytes `saveGlobalConfig` writes, for a caller that only plans the write. */
+export function serializeGlobalConfig(config) {
+    return JSON.stringify(config, null, 2) + '\n';
 }
 //# sourceMappingURL=global-config.js.map

package/dist/core/id.d.ts

@@ -4,6 +4,14 @@
  */
 export declare const KEBAB_ID_REGEX: RegExp;
 export declare function isKebabId(value: string): boolean;
+/**
+ * Best-effort normalization of an arbitrary name into the kebab grammar:
+ * lowercases, splits camelCase/PascalCase boundaries, and folds every
+ * non-alphanumeric run into a single hyphen. Used to turn a git repository
+ * name into a candidate store id; the result is only ever a candidate and
+ * is validated with {@link isKebabId} before use.
+ */
+export declare function toKebabCase(value: string): string;
 /** Human rendering of the grammar, shared so the wording never forks. */
 export declare const KEBAB_ID_DESCRIPTION = "must be kebab-case with lowercase letters, numbers, and single hyphen separators";
 /** The fix-line twin of KEBAB_ID_DESCRIPTION, shared for the same reason. */