@1mcp/agent 0.39.8 → 0.40.0-beta.1

package/build/commands/bootstrap/bootstrapOwnership.js

@@ -0,0 +1,144 @@
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+import { createProjectOwnerStorage, hasProjectOwnerState, resolveProjectOwnerStorage, temporaryProjectOwnerStorage, } from '../shared/projectOwnerStorage.js';
+import { assertNoProjectOwnerCalls, assertProjectOwnerAbsent, createHookProjectOwner, hookProjectOwnerPath, isProjectOwnerEnded, markProjectOwnerEnded, markProjectOwnerReleased, readHookThreadLocatorRecord, readProjectOwner, readProjectOwnerTargets, readProjectOwnerTerminal, recordHookThreadLocator, recordProjectOwnerAssignment, removeProjectOwner, withHookIdentityLock, withProjectOwnerLock, } from '../shared/projectOwnerStore.js';
+import { resolveProjectContext } from '../../config/projectConfigLoader.js';
+import { getConfigDir } from '../../constants.js';
+import { canonicalizeCheckoutPath } from '../../domains/project-selection/projectSelection.js';
+import { z } from 'zod';
+const inputSchema = z.object({
+    hook_event_name: z.enum(['SessionStart', 'SubagentStart', 'SessionEnd']),
+    session_id: z.string().min(1).max(512),
+    agent_id: z.string().min(1).max(512).optional(),
+    cwd: z.string().refine(path.isAbsolute).optional(),
+});
+function identity(options, input) {
+    const parsed = inputSchema.parse(JSON.parse(input));
+    if (parsed.hook_event_name !== options.event)
+        throw new Error('Hook event mismatch');
+    if (options.event === 'SessionStart' && parsed.agent_id)
+        throw new Error('SessionStart cannot establish worker assignment; use SubagentStart');
+    if (options.event === 'SubagentStart' && !parsed.agent_id)
+        throw new Error('Worker identity is missing');
+    if (options.event === 'SessionEnd' && parsed.agent_id)
+        throw new Error('SessionEnd does not verify worker termination');
+    return {
+        client: options.client,
+        sessionId: parsed.session_id,
+        ...(parsed.agent_id ? { agentId: parsed.agent_id } : {}),
+    };
+}
+export async function bootstrapOwner(options, input) {
+    if (options.event === 'SessionEnd')
+        throw new Error('End events cannot create ownership');
+    const hookIdentity = input.trim() ? identity(options, input) : undefined;
+    const storage = hookIdentity
+        ? await resolveProjectOwnerStorage(getConfigDir(options['config-dir']), hookIdentity.client, hookIdentity.agentId ?? hookIdentity.sessionId, hookIdentity.sessionId)
+        : undefined;
+    const establish = async () => {
+        let file = options['project-owner'];
+        let ownerIdentity = hookIdentity;
+        if (!file) {
+            if (!hookIdentity || !storage)
+                throw new Error('Missing hook owner identity');
+            const locator = await readHookThreadLocatorRecord(storage, hookIdentity.client, hookIdentity.agentId ?? hookIdentity.sessionId);
+            if (locator &&
+                (locator.identity.sessionId !== hookIdentity.sessionId || locator.identity.agentId !== hookIdentity.agentId))
+                throw new Error('Hook thread identity records disagree');
+            ownerIdentity = locator?.identity ?? hookIdentity;
+            const previous = locator?.ownerFile ?? hookProjectOwnerPath(storage, hookIdentity);
+            if (await isProjectOwnerEnded(previous))
+                ownerIdentity = { ...hookIdentity, generation: randomBytes(16).toString('hex') };
+            if (locator)
+                await readProjectOwner(previous);
+            file = await createHookProjectOwner(storage, ownerIdentity);
+        }
+        await readProjectOwner(file);
+        if (await isProjectOwnerEnded(file))
+            throw new Error('Session has ended; use project recover to retry recorded cleanup');
+        const parsed = input.trim() ? inputSchema.parse(JSON.parse(input)) : undefined;
+        let project = options.project;
+        if (options.event === 'SessionStart' && !project && !options['project-set'] && parsed?.cwd) {
+            project = [await canonicalizeCheckoutPath((await resolveProjectContext(parsed.cwd)).projectRoot, parsed.cwd)];
+        }
+        await recordProjectOwnerAssignment(file, {
+            version: 1,
+            worker: options.event === 'SubagentStart',
+            ...(project ? { project } : {}),
+            ...(options['project-set'] ? { 'project-set': options['project-set'] } : {}),
+        });
+        if (ownerIdentity && storage)
+            await recordHookThreadLocator(storage, ownerIdentity, file);
+        return file;
+    };
+    if (!hookIdentity || !storage)
+        return establish();
+    if (storage === temporaryProjectOwnerStorage(getConfigDir(options['config-dir'])))
+        await createProjectOwnerStorage(storage);
+    return withHookIdentityLock(storage, hookIdentity, establish);
+}
+export async function releaseSessionOwner(options, input, release) {
+    if (options.event !== 'SessionEnd')
+        throw new Error('Only verified SessionEnd may release ownership');
+    const hookIdentity = identity(options, input);
+    const storage = await resolveProjectOwnerStorage(getConfigDir(options['config-dir']), hookIdentity.client, hookIdentity.sessionId, hookIdentity.sessionId);
+    // Pin the generation before waiting for another lifecycle hook; cleanup never follows a newer locator.
+    const locator = await readHookThreadLocatorRecord(storage, hookIdentity.client, hookIdentity.sessionId);
+    const ownerIdentity = locator?.identity ?? hookIdentity;
+    const file = locator?.ownerFile ?? hookProjectOwnerPath(storage, hookIdentity);
+    if (!(await hasProjectOwnerState(storage, hookIdentity.client, hookIdentity.sessionId, hookIdentity.sessionId))) {
+        await assertProjectOwnerAbsent(file, hookIdentity);
+        return;
+    }
+    const selectedCredential = await readProjectOwner(file).catch((error) => {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    const selected = await withHookIdentityLock(storage, hookIdentity, async () => {
+        const currentCredential = await readProjectOwner(file).catch((error) => {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (currentCredential !== selectedCredential)
+            throw new Error('Session owner changed during terminal selection; no cleanup performed');
+        // An already-ended owner may be waiting on remote cleanup. Do not wait for its
+        // owner lock while holding the identity lock needed by a resumed startup.
+        if (await isProjectOwnerEnded(file))
+            return true;
+        return withProjectOwnerLock(file, async () => {
+            if (!currentCredential) {
+                await assertProjectOwnerAbsent(file, ownerIdentity);
+                return false;
+            }
+            await readProjectOwnerTargets(file);
+            await markProjectOwnerEnded(file, ownerIdentity);
+            return true;
+        });
+    });
+    if (selected)
+        await recoverEndedSessionOwner(file, release);
+}
+/** Recovery requires prior verified SessionEnd evidence, never age or a parent's lifetime. */
+export async function recoverEndedSessionOwner(file, release) {
+    await withProjectOwnerLock(file, async () => {
+        if ((await readProjectOwnerTerminal(file))?.released) {
+            await removeProjectOwner(file);
+            return;
+        }
+        if (!(await isProjectOwnerEnded(file)))
+            throw new Error('No verified terminal record; active or abandoned owners cannot be recovered automatically');
+        const targets = await readProjectOwnerTargets(file);
+        await releaseTargets(file, targets, release);
+    });
+}
+async function releaseTargets(file, targets, release) {
+    await assertNoProjectOwnerCalls(file);
+    const results = await Promise.allSettled(targets.map((target) => release(file, target)));
+    if (results.some((result) => result.status === 'rejected'))
+        throw new Error('Session ownership cleanup is incomplete');
+    await markProjectOwnerReleased(file);
+    await removeProjectOwner(file);
+}
+//# sourceMappingURL=bootstrapOwnership.js.map

package/build/commands/bootstrap/bootstrapOwnership.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrapOwnership.js","sourceRoot":"","sources":["../../../src/commands/bootstrap/bootstrapOwnership.ts"],"names":[],"mappings":"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"}

package/build/commands/bootstrap/index.d.ts

@@ -0,0 +1,3 @@
+import type { Argv } from 'yargs';
+export declare function setupBootstrapCommand(yargs: Argv): Argv;
+//# sourceMappingURL=index.d.ts.map

package/build/commands/bootstrap/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/bootstrap/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAElC,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CA6BvD"}

package/build/commands/bootstrap/index.js

@@ -0,0 +1,25 @@
+import { withProjectSelectionOptions } from '../shared/projectSelectionOptions.js';
+import { withGlobalOptions } from '../../globalOptions.js';
+import { runProductCommand } from '../../productTelemetry/commandScope.js';
+export function setupBootstrapCommand(yargs) {
+    return withGlobalOptions(yargs).command('bootstrap', 'Deliver agent hook instructions', (command) => withProjectSelectionOptions(command)
+        .env(false)
+        .option('client', { type: 'string', choices: ['codex', 'claude'], demandOption: true })
+        .option('event', {
+        type: 'string',
+        choices: ['SessionStart', 'SubagentStart', 'SessionEnd'],
+        demandOption: true,
+    })
+        .option('url', { type: 'string', describe: 'Runtime URL' })
+        .option('context', { type: 'string', describe: 'Named Runtime Target Context' })
+        .option('preset', { type: 'string' })
+        .option('tags', { type: 'array', string: true })
+        .option('tag-filter', { type: 'string' })
+        .epilogue('Worker assignments come from dispatch instructions, never parent cwd or session identity. Disabled or untrusted hooks remain a delivery coverage gap.'), async (argv) => {
+        return runProductCommand('project', async () => {
+            const { bootstrapCommand } = await import('./bootstrap.js');
+            await bootstrapCommand(argv);
+        });
+    });
+}
+//# sourceMappingURL=index.js.map

package/build/commands/bootstrap/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/bootstrap/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,iDAAiD,CAAC;AAC9F,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAI1E,MAAM,UAAU,qBAAqB,CAAC,KAAW;IAC/C,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC,OAAO,CACrC,WAAW,EACX,iCAAiC,EACjC,CAAC,OAAO,EAAE,EAAE,CACV,2BAA2B,CAAC,OAAO,CAAC;SACjC,GAAG,CAAC,KAAK,CAAC;SAEV,MAAM,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;SACtF,MAAM,CAAC,OAAO,EAAE;QACf,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,CAAC,cAAc,EAAE,eAAe,EAAE,YAAY,CAAC;QACxD,YAAY,EAAE,IAAI;KACnB,CAAC;SACD,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC;SAC1D,MAAM,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,8BAA8B,EAAE,CAAC;SAC/E,MAAM,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;SACpC,MAAM,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;SAC/C,MAAM,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;SACxC,QAAQ,CACP,uJAAuJ,CACxJ,EACL,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,OAAO,iBAAiB,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;YAC7C,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;YAC5D,MAAM,gBAAgB,CAAC,IAA8C,CAAC,CAAC;QACzE,CAAC,CAAC,CAAC;IACL,CAAC,CACF,CAAC;AACJ,CAAC"}

package/build/commands/cliSetup/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/cliSetup/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAElC,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CA4DtD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/cliSetup/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAElC,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CA6DtD"}

package/build/commands/cliSetup/index.js

@@ -1,7 +1,7 @@
-import { globalOptions } from '../../globalOptions.js';
+import { withGlobalOptions } from '../../globalOptions.js';
+import { exitProductCommand, runProductCommand } from '../../productTelemetry/commandScope.js';
 export function setupCliSetupCommand(yargs) {
-    return yargs.command('cli-setup', 'Install 1MCP CLI hooks and reference files for Codex and Claude', (commandYargs) => commandYargs
-        .options(globalOptions || {})
+    return withGlobalOptions(yargs).command('cli-setup', 'Install Codex and Claude CLI hooks and preparation skill', (commandYargs) => commandYargs
         .option('scope', {
         describe: 'Setup scope',
         type: 'string',
@@ -35,18 +35,20 @@ export function setupCliSetupCommand(yargs) {
         .example('$0 cli-setup --codex', 'Install global Codex hooks and reference files')
         .example('$0 cli-setup --claude --scope repo --repo-root .', 'Install repo-local Claude hooks and reference files')
         .example('$0 cli-setup --codex --scope all', 'Install global and repo-local Codex setup')
-        .epilogue('This command writes hook config and lightweight startup-file references. Errors are written to stderr only.'), async (argv) => {
-        const { configureGlobalLogger } = await import('../../logger/configureGlobalLogger.js');
-        const { cliSetupCommand } = await import('./cliSetup.js');
-        configureGlobalLogger(argv, 'stdio');
-        try {
-            await cliSetupCommand(argv);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            process.stderr.write(`${message}\n`);
-            process.exit(1);
-        }
+        .epilogue('This command writes hook config, startup-file references, and the preparation setup skill. It does not activate backend preparation. Errors are written to stderr only.'), async (argv) => {
+        return runProductCommand('config', async () => {
+            const { configureGlobalLogger } = await import('../../logger/configureGlobalLogger.js');
+            const { cliSetupCommand } = await import('./cliSetup.js');
+            configureGlobalLogger(argv, 'stdio');
+            try {
+                await cliSetupCommand(argv);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                process.stderr.write(`${message}\n`);
+                exitProductCommand(1);
+            }
+        });
     });
 }
 //# sourceMappingURL=index.js.map

package/build/commands/cliSetup/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/cliSetup/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAItD,MAAM,UAAU,oBAAoB,CAAC,KAAW;IAC9C,OAAO,KAAK,CAAC,OAAO,CAClB,WAAW,EACX,iEAAiE,EACjE,CAAC,YAAY,EAAE,EAAE,CACf,YAAY;SACT,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;SAC5B,MAAM,CAAC,OAAO,EAAE;QACf,QAAQ,EAAE,aAAa;QACvB,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC;QAClC,OAAO,EAAE,QAAQ;KAClB,CAAC;SACD,MAAM,CAAC,OAAO,EAAE;QACf,QAAQ,EAAE,oCAAoC;QAC9C,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,KAAK;KACf,CAAC;SACD,MAAM,CAAC,QAAQ,EAAE;QAChB,QAAQ,EAAE,qCAAqC;QAC/C,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,KAAK;KACf,CAAC;SACD,MAAM,CAAC,WAAW,EAAE;QACnB,QAAQ,EAAE,4CAA4C;QACtD,IAAI,EAAE,QAAQ;KACf,CAAC;SACD,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE;QACd,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC3D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAC9E,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;QAC5F,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;SACD,OAAO,CAAC,sBAAsB,EAAE,gDAAgD,CAAC;SACjF,OAAO,CACN,kDAAkD,EAClD,qDAAqD,CACtD;SACA,OAAO,CAAC,kCAAkC,EAAE,2CAA2C,CAAC;SACxF,QAAQ,CACP,6GAA6G,CAC9G,EACL,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,MAAM,EAAE,qBAAqB,EAAE,GAAG,MAAM,MAAM,CAAC,sCAAsC,CAAC,CAAC;QACvF,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;QAE1D,qBAAqB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC;YACH,MAAM,eAAe,CAAC,IAA6C,CAAC,CAAC;QACvE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;YACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/cliSetup/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAI9F,MAAM,UAAU,oBAAoB,CAAC,KAAW;IAC9C,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC,OAAO,CACrC,WAAW,EACX,0DAA0D,EAC1D,CAAC,YAAY,EAAE,EAAE,CACf,YAAY;SACT,MAAM,CAAC,OAAO,EAAE;QACf,QAAQ,EAAE,aAAa;QACvB,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC;QAClC,OAAO,EAAE,QAAQ;KAClB,CAAC;SACD,MAAM,CAAC,OAAO,EAAE;QACf,QAAQ,EAAE,oCAAoC;QAC9C,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,KAAK;KACf,CAAC;SACD,MAAM,CAAC,QAAQ,EAAE;QAChB,QAAQ,EAAE,qCAAqC;QAC/C,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,KAAK;KACf,CAAC;SACD,MAAM,CAAC,WAAW,EAAE;QACnB,QAAQ,EAAE,4CAA4C;QACtD,IAAI,EAAE,QAAQ;KACf,CAAC;SACD,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE;QACd,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC3D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAC9E,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;QAC5F,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;SACD,OAAO,CAAC,sBAAsB,EAAE,gDAAgD,CAAC;SACjF,OAAO,CACN,kDAAkD,EAClD,qDAAqD,CACtD;SACA,OAAO,CAAC,kCAAkC,EAAE,2CAA2C,CAAC;SACxF,QAAQ,CACP,yKAAyK,CAC1K,EACL,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,OAAO,iBAAiB,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;YAC5C,MAAM,EAAE,qBAAqB,EAAE,GAAG,MAAM,MAAM,CAAC,sCAAsC,CAAC,CAAC;YACvF,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;YAE1D,qBAAqB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YACrC,IAAI,CAAC;gBACH,MAAM,eAAe,CAAC,IAA6C,CAAC,CAAC;YACvE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;gBACrC,kBAAkB,CAAC,CAAC,CAAC,CAAC;YACxB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CACF,CAAC;AACJ,CAAC"}

package/build/commands/cliSetup/installPreparationSkill.d.ts

@@ -0,0 +1,8 @@
+export interface SkillInstallResult {
+    path: string;
+    changed: boolean;
+    status: 'installed' | 'updated' | 'unchanged' | 'conflict';
+    reason?: string;
+}
+export declare function installPreparationSkill(scopeRoot: string, skillsRelativePath: string, files?: Readonly<Record<string, string>>): Promise<SkillInstallResult>;
+//# sourceMappingURL=installPreparationSkill.d.ts.map

package/build/commands/cliSetup/installPreparationSkill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installPreparationSkill.d.ts","sourceRoot":"","sources":["../../../src/commands/cliSetup/installPreparationSkill.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAwDD,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,MAAM,EACjB,kBAAkB,EAAE,MAAM,EAC1B,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAyB,GAC9D,OAAO,CAAC,kBAAkB,CAAC,CA8B7B"}

package/build/commands/cliSetup/installPreparationSkill.js

@@ -0,0 +1,201 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, rename, rm, rmdir, stat, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { preparationSkillFiles } from './preparationSkill.generated.js';
+const SKILL_NAME = '1mcp-preparation-setup';
+const MANIFEST = '.1mcp-managed.json';
+const relativeFile = z.string().refine((value) => {
+    if (value === MANIFEST)
+        return false;
+    return value.split('/').every((part) => /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(part));
+});
+const manifestSchema = z.object({
+    schemaVersion: z.literal(1),
+    skill: z.literal(SKILL_NAME),
+    files: z.record(relativeFile, z.string().regex(/^[a-f0-9]{64}$/)),
+    pendingFiles: z.record(relativeFile, z.string().regex(/^[a-f0-9]{64}$/)).optional(),
+});
+function digest(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function isMissing(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+async function statIfPresent(file) {
+    try {
+        return await lstat(file);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+// Check every component below the selected scope, including dangling symlinks.
+async function pathConflict(root, file, directory) {
+    // The caller selected this root; aliases to it are valid, unlike redirects beneath it.
+    try {
+        if (!(await stat(root)).isDirectory())
+            return `Expected a directory: ${root}`;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+    const relative = path.relative(root, file);
+    const parts = relative ? relative.split(path.sep) : [];
+    let current = root;
+    for (let index = 0; index < parts.length; index++) {
+        current = path.join(current, parts[index]);
+        const stat = await statIfPresent(current);
+        if (!stat)
+            return undefined;
+        if (stat.isSymbolicLink())
+            return `Symlink preserved: ${current}`;
+        const needsDirectory = index < parts.length - 1 || directory;
+        if (needsDirectory && !stat.isDirectory())
+            return `Expected a directory: ${current}`;
+        if (!needsDirectory && !stat.isFile())
+            return `Expected a regular file: ${current}`;
+    }
+    return undefined;
+}
+async function writeAtomically(file, content) {
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, content, { flag: 'wx', mode: 0o600 });
+        await rename(temporary, file);
+    }
+    finally {
+        await unlink(temporary).catch((error) => {
+            if (!isMissing(error))
+                throw error;
+        });
+    }
+}
+export async function installPreparationSkill(scopeRoot, skillsRelativePath, files = preparationSkillFiles) {
+    const root = path.resolve(scopeRoot);
+    const destination = path.join(root, skillsRelativePath, SKILL_NAME);
+    const conflict = (reason) => ({
+        path: destination,
+        changed: false,
+        status: 'conflict',
+        reason,
+    });
+    const directoryConflict = await pathConflict(root, destination, true);
+    if (directoryConflict)
+        return conflict(directoryConflict);
+    await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+    const lockPath = `${destination}.install-lock`;
+    try {
+        await mkdir(lockPath, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
+            return conflict(`Installation lock exists: ${lockPath}. Confirm its installer stopped before removing the lock and retrying.`);
+        }
+        throw error;
+    }
+    try {
+        return await installUnderLock(root, destination, lockPath, files);
+    }
+    finally {
+        await rm(path.join(lockPath, 'staging'), { recursive: true, force: true });
+        await rmdir(lockPath);
+    }
+}
+async function installUnderLock(root, destination, lockPath, files) {
+    const conflict = (reason) => ({
+        path: destination,
+        changed: false,
+        status: 'conflict',
+        reason,
+    });
+    const directoryConflict = await pathConflict(root, destination, true);
+    if (directoryConflict)
+        return conflict(directoryConflict);
+    const exists = await statIfPresent(destination);
+    const manifestPath = path.join(destination, MANIFEST);
+    let previous = {};
+    let previousManifest;
+    let pending;
+    if (exists) {
+        const manifestConflict = await pathConflict(root, manifestPath, false);
+        if (manifestConflict)
+            return conflict(manifestConflict);
+        if (!(await statIfPresent(manifestPath)))
+            return conflict('Existing skill has no 1MCP ownership manifest');
+        previousManifest = await readFile(manifestPath, 'utf8');
+        try {
+            const manifest = manifestSchema.parse(JSON.parse(previousManifest));
+            previous = manifest.files;
+            pending = manifest.pendingFiles;
+        }
+        catch {
+            return conflict('Invalid 1MCP ownership manifest; existing skill preserved');
+        }
+        if (!previous['SKILL.md'])
+            return conflict('Ownership manifest does not identify SKILL.md');
+    }
+    // Preflight the whole skill so one conflict cannot leave a partially upgraded recipe guide.
+    const contents = new Map();
+    for (const relative of new Set([...Object.keys(previous), ...Object.keys(pending ?? {}), ...Object.keys(files)])) {
+        relativeFile.parse(relative);
+        const file = path.join(destination, relative);
+        const fileConflict = await pathConflict(root, file, false);
+        if (fileConflict)
+            return conflict(fileConflict);
+        if (!(await statIfPresent(file))) {
+            // A missing pending addition may have been published and then deleted by the user.
+            if (!previous[relative] && pending?.[relative])
+                return conflict(`Pending managed file is missing: ${relative}`);
+            if (!previous[relative])
+                continue;
+            if (pending && !Object.hasOwn(pending, relative))
+                continue;
+            return conflict(`Managed file was removed: ${relative}`);
+        }
+        const content = await readFile(file, 'utf8');
+        if (!previous[relative] && !pending?.[relative])
+            return conflict(`Unmanaged file preserved: ${relative}`);
+        const hash = digest(content);
+        if (hash !== previous[relative] && hash !== pending?.[relative])
+            return conflict(`Locally edited file preserved: ${relative}`);
+        contents.set(relative, content);
+    }
+    const nextManifest = `${JSON.stringify({
+        schemaVersion: 1,
+        skill: SKILL_NAME,
+        files: Object.fromEntries(Object.entries(files).map(([file, content]) => [file, digest(content)])),
+    }, null, 2)}\n`;
+    if (previousManifest === nextManifest)
+        return { path: destination, changed: false, status: 'unchanged' };
+    const writeRoot = exists ? destination : path.join(lockPath, 'staging');
+    if (exists) {
+        // Journal both accepted and intended bytes before replacing any managed file.
+        await writeAtomically(manifestPath, `${JSON.stringify({
+            schemaVersion: 1,
+            skill: SKILL_NAME,
+            files: Object.fromEntries([...contents].map(([file, content]) => [file, digest(content)])),
+            pendingFiles: Object.fromEntries(Object.entries(files).map(([file, content]) => [file, digest(content)])),
+        }, null, 2)}\n`);
+    }
+    for (const [relative, content] of Object.entries(files)) {
+        if (contents.get(relative) === content)
+            continue;
+        await writeAtomically(path.join(writeRoot, relative), content);
+    }
+    for (const relative of contents.keys()) {
+        if (Object.hasOwn(files, relative))
+            continue;
+        await unlink(path.join(destination, relative));
+    }
+    await writeAtomically(path.join(writeRoot, MANIFEST), nextManifest);
+    if (!exists)
+        await rename(writeRoot, destination);
+    return { path: destination, changed: true, status: exists ? 'updated' : 'installed' };
+}
+//# sourceMappingURL=installPreparationSkill.js.map

package/build/commands/cliSetup/installPreparationSkill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"installPreparationSkill.js","sourceRoot":"","sources":["../../../src/commands/cliSetup/installPreparationSkill.ts"],"names":[],"mappings":"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"}

package/build/commands/cliSetup/preparationSkill.generated.d.ts

@@ -0,0 +1,2 @@
+export declare const preparationSkillFiles: Readonly<Record<string, string>>;
+//# sourceMappingURL=preparationSkill.generated.d.ts.map

package/build/commands/cliSetup/preparationSkill.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preparationSkill.generated.d.ts","sourceRoot":"","sources":["../../../src/commands/cliSetup/preparationSkill.generated.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASlE,CAAC"}

package/build/commands/cliSetup/preparationSkill.generated.js

@@ -0,0 +1,8 @@
+// Generated by scripts/generate-preparation-skill.mjs. Edit skills/1mcp-preparation-setup instead.
+export const preparationSkillFiles = {
+    'references/code-review-graph.md': "# Code Review Graph\n\nInspect the installed version's public build/update and status interfaces. Match the readiness probe's expected file set to the actual parser-supported source universe. Some YAML files produce no graph nodes; a generic extension scan can otherwise demand synchronization forever even after a successful native build.\n\nVerify supported additions, edits, and deletions, including untracked files. Do not drop YAML wholesale to silence a mismatch: supported Ansible or Spring content may still need indexing. If the public CLI skips a supported source class, identify the gap; use another documented native interface only after version-specific verification.\n\nCheck completed-build markers, checkout identity, source hashes, and coverage together. Node counts or a build SHA alone cannot establish dirty-source freshness. Use the installed CLI's documented output flags rather than assuming `--json` exists.\n\nAn earlier 2.3.9 integration stored absolute checkout paths. Do not seed another worktree by copying that database; initialize the target natively unless the installed version provides verified relocation support. Native operation-wide writer ownership and cancellation require their own evidence, even when fixture tests pass.\n",
+    'references/codegraph.md': "# CodeGraph\n\nInspect the installed version's native initialization, synchronization, status, and locking interfaces. Define which source files and extraction versions the readiness check covers. Watcher configuration matters: a disabled watcher requires explicit freshness checks and synchronization.\n\n## Optional worktree seeding\n\nUse seeding only after verifying the installed version stores portable relative paths and supports a compatible snapshot. Confirm repository identity, index schema/extraction version, integrity, and native writer ownership. A matching commit alone does not establish compatibility or dirty-source freshness.\n\nFor compatible SQLite indexes, use the SQLite online backup interface to obtain a consistent snapshot. Do not copy a live database file, WAL, lock, or process state blindly. Preserve an existing destination index. Put the optimization in the recipe's helper rather than modifying 1MCP runtime code.\n\nAfter seeding, always run native synchronization and the readiness probe. Verify worktree-only symbol additions, edits, and deletion through fresh 1MCP queries, and confirm the original checkout remains isolated. If portability cannot be established, use ordinary native initialization; if a writer conflict exists, report the conflict rather than bypassing it.\n\nEarlier experiments on CodeGraph 1.6.2 demonstrated relative-path seeding but did not establish universal writer coordination or cancellation guarantees. Recheck the installed version; do not copy machine-specific executable paths or treat those experiments as current acceptance.\n",
+    'references/serena.md': "# Serena\n\nSeparate project configuration creation, language-server dependencies/startup, indexing/cache warmup, and onboarding. Choose and document the requested scope. A create-only recipe may report configuration readiness, but must not claim that the language server, symbol index, or onboarding is ready.\n\nUse the installed version's public project commands and preserve existing project settings. Verify that rerunning initialization leaves user configuration intact and identify how concurrent native configuration writers are coordinated. Keep dependency installation separate unless authorized; never mark onboarding complete on the user's behalf merely to satisfy a probe.\n\nAfter configuration preparation, verify a real symbol lookup in the selected checkout through 1MCP. Missing dependencies or failed language-server startup remain native usability gaps even if the configuration probe passes. Gate only operations for which the recipe's declared scope is appropriate.\n\nDo not copy running language-server state or caches between worktrees without native portability support. Earlier Serena 2.0.0 experiments covered create-only preparation, not general language/platform readiness or cancellation. Recheck current behavior before adopting that approach.\n",
+    'SKILL.md': '---\nname: 1mcp-preparation-setup\ndescription: Configure 1MCP backend preparation for selected projects and worktrees. Use when installing or adapting a preparation recipe, authoring a missing recipe or helper, enabling automatic preparation, or diagnosing recipe readiness. Covers dynamic MCP backends; ordinary MCP server launch setup uses mcp setup.\n---\n\n# Set up backend preparation\n\nDeliver a configured recipe and evidence for its declared readiness scope. Installing this skill alone changes no backend settings. Use the installed 1MCP CLI and its current help and instructions; recipe support and native backend behavior vary by version.\n\n## Establish the target\n\nIdentify the runtime (`--url` or `--context`, plus configuration location and filters), assigned checkout or selected project-set member, configured server name, native version, current recipe and effective permissions. Normal local calls use the verified startup or worker assignment and omit `--project` and `--project-owner`. Keep any explicit target override through discovery, preparation, schema inspection, and invocation; an override does not change the session default.\n\nFollow current bootstrap guidance for ownership. Codex hosts with trustworthy thread lookup resolve their own owner automatically; hosts without that integration use their own bootstrap-provided `--project-owner` reference. Each worker needs its own explicit assignment and owner. Explicit `--url` calls remain credentialless unless an owner is explicitly supplied; local credentials do not authorize remote lifecycle controls. Resolve missing assignment before project-specific work.\n\nReuse current hook-delivered instructions; otherwise fetch scoped `1mcp instructions`. Inspect the server and applicable instructions, then tool schemas before invoking tools through `1mcp run`. `1mcp project prepare inspect <server>` checks readiness even when discovery is empty and does not start preparation. Native CLI help and read-only diagnostics can establish recipe behavior; upstream MCP calls stay routed through 1MCP.\n\nRead only the matching backend reference: [CodeGraph](references/codegraph.md), [Code Review Graph](references/code-review-graph.md), or [Serena](references/serena.md). For other backends, discover their native public setup and readiness interfaces. These examples are conditional techniques, not bundled production recipes.\n\n## Resolve or author the recipe\n\nReuse a compatible supplied recipe when available. Otherwise read the current [recipe contract](https://github.com/1mcp-app/agent/blob/main/docs/development/backend-preparation-recipes.md), checking it against the installed version. In a source checkout, use its matching document and schemas. Produce a named `configured-command` JSON definition and only the helper files needed to translate native behavior into that contract.\n\n- Declare backend/version/platform compatibility, readiness scope, affected tools, supported actions, and helper identity. Keep machine-specific paths and inputs in runtime configuration. Commands use executable/argument arrays, literal placeholders, and the selected checkout as cwd; they are not shell command strings.\n- Prefer native public commands. Validate recipe shape with the installed runtime\'s schema/loading path. The demonstration fixture proves the generic contract only; it is not an integration for a native indexer.\n- Probes and optional progress commands must be read-only and bounded. For an index, check checkout identity, completeness, supported source coverage, and freshness including dirty and untracked additions, edits, and deletions. A file existing or a successful action exit is insufficient.\n- Map verified states to `ready`, `required` with its supported action, or `conflict`. In the current contract, unknown readiness comes from an unmapped exit or failed check, not a configured `state: "unknown"`. Never translate uncertainty into ready.\n- Establish native writer coordination and attached-process cancellation behavior. Preserve foreign locks and work. Do not infer those guarantees from 1MCP process containment or fixture success.\n- Bump recipe/helper revisions when behavior changes; declare helper files so identity reflects their content. Avoid changing helpers during admitted jobs.\n\nIf native guarantees remain unverified, explain the specific limitation and affected scope. Experimental installation is allowed when the user explicitly accepts it, including acceptance already given in this task. Experimental status never licenses a false readiness result. A request to inspect or draft alone does not authorize activation.\n\n## Apply authorized configuration\n\nBack up the current configuration and compare it again before applying a scoped change. Preserve unrelated fields and existing explicit backend/project disables. Attach the named definition by matching ID and absolute file path to the existing server/template; keep `allowedActions` separate from the recipe\'s declared actions.\n\nFor requested automatic preparation across authorized checkouts, use a named definition with `activation: "setup"`. For project-only automatic preparation, retain project opt-in and update the effective `.1mcprc` by configured server name, respecting linked-worktree inheritance. Clarify activation scope only when it cannot be inferred from the request. Do not combine named and inline integration definitions.\n\nAuthorize only the requested actions. Installation, paid services, rebuilds, wider checkout access, and removal of explicit disables require their own applicable authorization. A denied action is not a reason to widen permissions. Read back effective runtime configuration and readiness after installation; a written file does not establish that the runtime loaded it.\n\n## Verify and close out\n\nUse an isolated checkout for source-changing checks. Verify the declared scope with a cold checkout, an already-ready checkout, supported source changes, and checkout isolation. Test conflict and failure behavior without interfering with foreign processes. If native concurrency/cancellation cannot be exercised, report that gap explicitly.\n\n1. Inspect readiness for the exact target and operation. Start permitted work with `1mcp project prepare start <server>` only when needed.\n2. Follow the returned job with `status` or bounded `wait --wait-ms 5000`. Keep the same runtime, project, owner, filters, and operation. A job performs one action; terminal failure or another required action needs diagnosis and deliberate retry, not a retry loop.\n3. Verify the post-action probe. Refresh server discovery and inspect the tool schema, then submit a fresh tool call. Preparation never replays the original request. Check that the returned result belongs to the selected checkout and reflects the test source.\n4. Release only task-owned bindings when their work is finished. For disposable checkout removal, follow current `project release` and manager/operator `project drain` guidance; require confirmed completion before removal and preserve other owners. Turn completion alone is not session termination. Do not add Git or client hooks as a side effect of recipe setup.\n\nReport changed paths, activation scope and allowed actions, configuration/readback evidence, probe and real-tool results, and any unverified guarantees. Distinguish installed configuration, recipe readiness, and native usability. For rollback, disable just the server\'s `preparation.enabled` or the selected project\'s preparation preference; restore backups only after checking for intervening unrelated changes. Name retained verification resources and their blockers instead of claiming cleanup finished.\n',
+};
+//# sourceMappingURL=preparationSkill.generated.js.map

package/build/commands/cliSetup/preparationSkill.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preparationSkill.generated.js","sourceRoot":"","sources":["../../../src/commands/cliSetup/preparationSkill.generated.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,MAAM,CAAC,MAAM,qBAAqB,GAAqC;IACrE,iCAAiC,EAC/B,kvCAAkvC;IACpvC,yBAAyB,EACvB,gkDAAgkD;IAClkD,sBAAsB,EACpB,+vCAA+vC;IACjwC,UAAU,EACR,ujPAAujP;CAC1jP,CAAC"}

package/build/commands/cliSetup/setupFiles.d.ts

@@ -1,4 +1,5 @@
 import { renderManagedDocContent, renderStartupDocManagedBlock, upsertStartupDocManagedBlock } from '../../core/instructions/instructionsDistribution.js';
+import { type SkillInstallResult } from './installPreparationSkill.js';
 export declare const CLI_SETUP_TARGETS: readonly ["codex", "claude"];
 export type CliSetupTarget = (typeof CLI_SETUP_TARGETS)[number];
 export declare const CLI_SETUP_SCOPES: readonly ["global", "repo", "all"];
@@ -11,7 +12,9 @@ interface WriteCliSetupOptions {
 export interface CliSetupWriteResult {
     path: string;
     changed: boolean;
-    kind: 'hook' | 'startup-doc' | 'managed-doc';
+    kind: 'hook' | 'startup-doc' | 'managed-doc' | 'skill';
+    status?: SkillInstallResult['status'];
+    reason?: string;
     target: CliSetupTarget;
     scope: Exclude<CliSetupScope, 'all'>;
 }
@@ -19,4 +22,5 @@ export declare function resolveCliSetupScope(rawScope?: string): CliSetupScope;
 export declare function writeCliSetupFiles(options: WriteCliSetupOptions): Promise<CliSetupWriteResult[]>;
 export declare function formatCliSetupOutput(results: CliSetupWriteResult[]): string;
 export { renderManagedDocContent, renderStartupDocManagedBlock, upsertStartupDocManagedBlock };
+export declare function upsertHooks(existing: Record<string, unknown>, target: CliSetupTarget): Record<string, unknown>;
 //# sourceMappingURL=setupFiles.d.ts.map

package/build/commands/cliSetup/setupFiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setupFiles.d.ts","sourceRoot":"","sources":["../../../src/commands/cliSetup/setupFiles.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAE5B,4BAA4B,EAC7B,MAAM,oDAAoD,CAAC;AAK5D,eAAO,MAAM,iBAAiB,8BAA+B,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,eAAO,MAAM,gBAAgB,oCAAqC,CAAC;AACnE,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAe9D,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,aAAa,CAAC;IAC7C,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,OAAO,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;CACtC;AAsBD,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,aAAa,CAWrE;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAiBtG;AA2BD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,MAAM,CAO3E;AAED,OAAO,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,4BAA4B,EAAE,CAAC"}
+{"version":3,"file":"setupFiles.d.ts","sourceRoot":"","sources":["../../../src/commands/cliSetup/setupFiles.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAE5B,4BAA4B,EAC7B,MAAM,oDAAoD,CAAC;AAK5D,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAEhG,eAAO,MAAM,iBAAiB,8BAA+B,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,eAAO,MAAM,gBAAgB,oCAAqC,CAAC;AACnE,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAe9D,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,aAAa,GAAG,OAAO,CAAC;IACvD,MAAM,CAAC,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,OAAO,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;CACtC;AAwBD,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,aAAa,CAWrE;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAqBtG;AA2BD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,MAAM,CAW3E;AAQD,OAAO,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,4BAA4B,EAAE,CAAC;AA2F/F,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAS9G"}