@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ebaebc4

package/foundation/integrations/integrations.test.mjs

@@ -77,6 +77,7 @@ describe('configured integrations', () => {
     const loaded = project.loadedIntegrations[0];
     // Identity comes from package.json, not the manifest.
     expect(loaded.name).toBe('@acme/widgets');
+    expect(loaded.providerId).toBe('@acme/widgets');
     expect(loaded.version).toBe('1.2.3');
     expect(loaded.components).toBe(path.join(pkgDir, 'docs'));
     expect(loaded.templates).toBe(path.join(pkgDir, 'blocks'));
@@ -84,6 +85,43 @@ describe('configured integrations', () => {
     expect(loaded.issuesUrl).toBe('https://example.com/issues');
   });
 
+  it('preserves provider identity across an explicit package rename', async () => {
+    writeManifestPackage(tmpDir, {
+      body: `export default {providerId: '@acme/legacy-widgets'};\n`,
+    });
+
+    const [loaded] = await loadIntegrations(['@acme/widgets'], {cwd: tmpDir});
+    expect(loaded.name).toBe('@acme/widgets');
+    expect(loaded.providerId).toBe('@acme/legacy-widgets');
+    expect(loaded.__unknownKeys).toEqual([]);
+  });
+
+  it('deduplicates package aliases by canonical provider identity', async () => {
+    writeManifestPackage(tmpDir, {body: `export default {};\n`});
+    const aliasDir = path.join(
+      tmpDir,
+      'node_modules',
+      '@acme',
+      'widgets-alias',
+    );
+    fs.mkdirSync(aliasDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(aliasDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+    );
+    fs.writeFileSync(
+      path.join(aliasDir, 'astryx.integration.mjs'),
+      `export default {};\n`,
+    );
+
+    const loaded = await loadIntegrations(
+      ['@acme/widgets', '@acme/widgets-alias'],
+      {cwd: tmpDir},
+    );
+    expect(loaded).toHaveLength(1);
+    expect(loaded[0].providerId).toBe('@acme/widgets');
+  });
+
   it('makes integration components discoverable', async () => {
     const pkgDir = writeManifestPackage(tmpDir, {
       body: `export default { components: './docs' };\n`,
@@ -207,6 +245,347 @@ describe('configured integrations', () => {
   });
 });
 
+describe('provider identity conflicts', () => {
+  /**
+   * Install one integration package that contributes a single component.
+   * @param {string} dir directory under node_modules
+   * @param {{name: string, version: string}} pkg package.json identity
+   * @param {Record<string, unknown>} manifest extra manifest fields
+   * @param {string} component the component it contributes
+   */
+  function installPackage(dir, pkg, manifest, component) {
+    const pkgDir = path.join(tmpDir, 'node_modules', ...dir.split('/'));
+    const componentsDir = path.join(pkgDir, 'components');
+    fs.mkdirSync(componentsDir, {recursive: true});
+    fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify(pkg));
+    fs.writeFileSync(
+      path.join(pkgDir, 'astryx.integration.mjs'),
+      `export default ${JSON.stringify({components: './components', ...manifest})};\n`,
+    );
+    fs.writeFileSync(
+      path.join(componentsDir, `${component}.doc.mjs`),
+      `export default {type: 'component', name: '${component}', props: []};\n`,
+    );
+    fs.writeFileSync(
+      path.join(componentsDir, `${component}.tsx`),
+      `export function ${component}() { return null; }\n`,
+    );
+  }
+
+  /** @param {string[]} integrations */
+  function configure(integrations) {
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.config.mjs'),
+      `export default ${JSON.stringify({integrations})};\n`,
+    );
+  }
+
+  /**
+   * Make the project directory itself the package being authored.
+   * @param {Record<string, unknown>} pkg package.json fields
+   * @param {Record<string, unknown>} manifest extra manifest fields
+   * @param {string} component the component it contributes
+   */
+  function writeLocalPackage(pkg, manifest, component) {
+    const componentsDir = path.join(tmpDir, 'local-components');
+    fs.mkdirSync(componentsDir, {recursive: true});
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify(pkg));
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      `export default ${JSON.stringify({components: './local-components', ...manifest})};\n`,
+    );
+    fs.writeFileSync(
+      path.join(componentsDir, `${component}.doc.mjs`),
+      `export default {type: 'component', name: '${component}', props: []};\n`,
+    );
+    fs.writeFileSync(
+      path.join(componentsDir, `${component}.tsx`),
+      `export function ${component}() { return null; }\n`,
+    );
+  }
+
+  /** @param {import('../config/project.mjs').Project} project */
+  async function conflictIssues(project) {
+    return (await project.issues()).filter(
+      issue => issue.code === 'duplicate_provider',
+    );
+  }
+
+  it('keeps the first package and reports a different package claiming its ID', async () => {
+    installPackage(
+      '@acme/widgets',
+      {name: '@acme/widgets', version: '1.0.0'},
+      {},
+      'Widget',
+    );
+    installPackage(
+      '@acme/renamed',
+      {name: '@acme/renamed', version: '2.0.0'},
+      {providerId: '@acme/widgets'},
+      'RenamedWidget',
+    );
+    configure(['@acme/widgets', '@acme/renamed']);
+
+    const loaded = await loadIntegrations(['@acme/widgets', '@acme/renamed'], {
+      cwd: tmpDir,
+    });
+    expect(loaded.map(integration => integration.name)).toEqual([
+      '@acme/widgets',
+      '@acme/renamed',
+    ]);
+    expect(loaded[1]).toMatchObject({
+      providerId: '@acme/widgets',
+      __providerConflict: {
+        providerId: '@acme/widgets',
+        claimedBy: '@acme/widgets',
+      },
+    });
+    expect(loaded[1].components).toBeUndefined();
+
+    const project = await Project.load(tmpDir, {fresh: true});
+    const owned = (await project.components()).map(component => [
+      component.package,
+      component.name,
+    ]);
+    expect(owned).toContainEqual(['@acme/widgets', 'Widget']);
+    expect(owned.some(([pkg]) => pkg === '@acme/renamed')).toBe(false);
+    expect(await project.issues()).toContainEqual(
+      expect.objectContaining({
+        package: '@acme/renamed@2.0.0',
+        code: 'duplicate_provider',
+        severity: 'warning',
+        message: expect.stringContaining(
+          '@acme/widgets@1.0.0 loads first and is used',
+        ),
+      }),
+    );
+  });
+
+  it('reports the same package configured again at another version', async () => {
+    installPackage(
+      '@acme/widgets',
+      {name: '@acme/widgets', version: '1.0.0'},
+      {},
+      'Widget',
+    );
+    installPackage(
+      'widgets-next',
+      {name: '@acme/widgets', version: '2.0.0'},
+      {},
+      'NextWidget',
+    );
+    configure(['@acme/widgets', 'widgets-next']);
+
+    const project = await Project.load(tmpDir, {fresh: true});
+    const owned = (await project.components()).map(component => component.name);
+    expect(owned).toContain('Widget');
+    expect(owned).not.toContain('NextWidget');
+    expect(await project.issues()).toContainEqual(
+      expect.objectContaining({
+        package: '@acme/widgets@2.0.0',
+        code: 'duplicate_provider',
+        severity: 'warning',
+        message: expect.stringContaining('(from "widgets-next")'),
+      }),
+    );
+  });
+
+  it('reports an autolinked dependency that claims a configured ID', async () => {
+    installPackage(
+      '@acme/widgets',
+      {name: '@acme/widgets', version: '1.0.0'},
+      {},
+      'Widget',
+    );
+    installPackage(
+      '@acme/renamed',
+      {name: '@acme/renamed', version: '2.0.0'},
+      {providerId: '@acme/widgets'},
+      'RenamedWidget',
+    );
+    configure(['@acme/widgets']);
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({
+        name: 'consumer',
+        dependencies: {'@acme/renamed': '2.0.0'},
+      }),
+    );
+
+    const project = await Project.load(tmpDir, {fresh: true});
+    expect(
+      project.loadedIntegrations.find(
+        integration => integration.name === '@acme/renamed',
+      ),
+    ).toMatchObject({
+      __autolinked: true,
+      __providerConflict: {claimedBy: '@acme/widgets'},
+    });
+    expect(await project.issues()).toContainEqual(
+      expect.objectContaining({
+        package: '@acme/renamed@2.0.0',
+        code: 'duplicate_provider',
+      }),
+    );
+  });
+
+  it("reports a set-aside package whose spec is the winner's name", async () => {
+    installPackage(
+      'widgets-old',
+      {name: '@acme/widgets', version: '1.0.0'},
+      {},
+      'OldWidget',
+    );
+    installPackage(
+      '@acme/widgets',
+      {name: '@acme/widgets', version: '2.0.0'},
+      {},
+      'NewWidget',
+    );
+    configure(['widgets-old', '@acme/widgets']);
+
+    const project = await Project.load(tmpDir, {fresh: true});
+    const owned = (await project.components()).map(component => component.name);
+    expect(owned).toContain('OldWidget');
+    expect(owned).not.toContain('NewWidget');
+    expect(await conflictIssues(project)).toEqual([
+      expect.objectContaining({
+        package: '@acme/widgets@2.0.0',
+        severity: 'warning',
+        message: expect.stringContaining(
+          '@acme/widgets@2.0.0 and @acme/widgets@1.0.0 (from "widgets-old") both claim',
+        ),
+      }),
+    ]);
+  });
+
+  it('reports an unversioned set-aside package whose spec is the winner\'s name', async () => {
+    installPackage(
+      'widgets-old',
+      {name: '@acme/widgets', version: '1.0.0'},
+      {},
+      'OldWidget',
+    );
+    installPackage('@acme/widgets', {name: '@acme/widgets'}, {}, 'NewWidget');
+    configure(['widgets-old', '@acme/widgets']);
+
+    const project = await Project.load(tmpDir, {fresh: true});
+    expect(await conflictIssues(project)).toEqual([
+      expect.objectContaining({
+        package: '@acme/widgets',
+        message: expect.stringContaining(
+          '@acme/widgets@1.0.0 (from "widgets-old") loads first and is used',
+        ),
+      }),
+    ]);
+  });
+
+  it('reports an autolinked alias of the same package at another version', async () => {
+    installPackage(
+      '@acme/legacy-ui',
+      {name: '@acme/ui', version: '0.1.22'},
+      {},
+      'LegacyButton',
+    );
+    installPackage(
+      '@acme/ui',
+      {name: '@acme/ui', version: '1.0.0'},
+      {},
+      'NewButton',
+    );
+    fs.rmSync(path.join(tmpDir, 'astryx.config.mjs'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({
+        name: 'consumer',
+        dependencies: {
+          '@acme/legacy-ui': 'npm:@acme/ui@0.1.22',
+          '@acme/ui': '1.0.0',
+        },
+      }),
+    );
+
+    const project = await Project.load(tmpDir, {fresh: true});
+    const owned = (await project.components()).map(component => component.name);
+    expect(owned).toContain('LegacyButton');
+    expect(owned).not.toContain('NewButton');
+    expect(await conflictIssues(project)).toEqual([
+      expect.objectContaining({
+        package: '@acme/ui@1.0.0',
+        message: expect.stringContaining(
+          '@acme/ui@1.0.0 and @acme/ui@0.1.22 (from "@acme/legacy-ui") both claim',
+        ),
+      }),
+    ]);
+  });
+
+  it('recomputes conflicts after the authored package replaces its installed copy', async () => {
+    installPackage(
+      '@acme/widgets',
+      {name: '@acme/widgets', version: '1.0.0'},
+      {},
+      'Widget',
+    );
+    installPackage(
+      '@acme/renamed',
+      {name: '@acme/renamed', version: '2.0.0'},
+      {providerId: '@acme/widgets'},
+      'RenamedWidget',
+    );
+    configure(['@acme/widgets', '@acme/renamed']);
+    writeLocalPackage(
+      {name: '@acme/widgets', version: '3.0.0-dev'},
+      {providerId: '@acme/widgets-next'},
+      'LocalWidget',
+    );
+
+    const project = await Project.load(tmpDir, {fresh: true});
+    expect(
+      project.loadedIntegrations.some(
+        integration => integration.__providerConflict,
+      ),
+    ).toBe(false);
+    const owned = (await project.components()).map(component => component.name);
+    expect(owned).toEqual(
+      expect.arrayContaining(['LocalWidget', 'RenamedWidget']),
+    );
+    expect(owned).not.toContain('Widget');
+    expect(await conflictIssues(project)).toEqual([]);
+  });
+
+  it('lets the package being authored win over its installed predecessor', async () => {
+    installPackage(
+      '@acme/widgets',
+      {name: '@acme/widgets', version: '1.0.0'},
+      {},
+      'Widget',
+    );
+    fs.rmSync(path.join(tmpDir, 'astryx.config.mjs'));
+    writeLocalPackage(
+      {
+        name: '@acme/renamed',
+        version: '2.0.0-dev',
+        devDependencies: {'@acme/widgets': '1.0.0'},
+      },
+      {providerId: '@acme/widgets'},
+      'RenamedWidget',
+    );
+
+    const project = await Project.load(tmpDir, {fresh: true});
+    const owned = (await project.components()).map(component => component.name);
+    expect(owned).toContain('RenamedWidget');
+    expect(owned).not.toContain('Widget');
+    expect(await conflictIssues(project)).toEqual([
+      expect.objectContaining({
+        package: '@acme/widgets@1.0.0',
+        message: expect.stringContaining(
+          '@acme/renamed@2.0.0-dev is the package being authored, so it is used',
+        ),
+      }),
+    ]);
+  });
+});
+
 describe('local integration self-resolution', () => {
   it('preserves a valid gapReport named export', async () => {
     fs.writeFileSync(
@@ -225,7 +604,11 @@ export default {};
 
     const loaded = await loadLocalIntegration(tmpDir, {fresh: true});
 
-    expect(loaded).toMatchObject({name: '@acme/local', __local: true});
+    expect(loaded).toMatchObject({
+      name: '@acme/local',
+      providerId: '@acme/local',
+      __local: true,
+    });
     expect(loaded?.__gapReport?.audience).toBe('internal');
     expect(
       loaded?.__gapReport?.handle(

package/foundation/integrations/provider-conflicts.test.mjs

@@ -0,0 +1,125 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Provider-identity conflicts proved against the repository's real
+ * integration packages instead of hand-written fixtures: the Lab package as it
+ * ships, beside a copy of Charts whose manifest also claims Lab's provider ID.
+ *
+ * Fixtures live under a repo-local temp dir, not /tmp, because Vite refuses to
+ * dynamically import a module from outside the project root.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {Project} from '../config/project.mjs';
+import {doctor} from '../../api/doctor/doctor.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+const REPO = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../..',
+);
+const CHARTS = path.join(REPO, 'packages', 'charts');
+const SLOW = 60_000;
+
+/** Both packages are named; Lab is named as the one used, Charts as set aside. */
+const WINNER_NAMED =
+  /@astryxdesign\/charts@\S+ and @astryxdesign\/lab@\S+ both claim provider ID "@astryxdesign\/lab"\. @astryxdesign\/lab@\S+ loads first and is used; @astryxdesign\/charts@\S+ contributes nothing/u;
+
+let consumer;
+let chartsManifest;
+
+beforeEach(() => {
+  consumer = fs.mkdtempSync(
+    path.join(process.cwd(), '.astryx-provider-conflict-'),
+  );
+  const scope = path.join(consumer, 'node_modules', '@astryxdesign');
+  fs.mkdirSync(scope, {recursive: true});
+  fs.symlinkSync(
+    path.join(REPO, 'packages', 'lab'),
+    path.join(scope, 'lab'),
+    'dir',
+  );
+
+  const charts = path.join(scope, 'charts');
+  fs.cpSync(CHARTS, charts, {
+    recursive: true,
+    filter: source => {
+      const [top] = path.relative(CHARTS, source).split(path.sep);
+      return top !== 'node_modules' && top !== 'dist';
+    },
+  });
+  chartsManifest = path.join(charts, 'astryx.integration.mjs');
+  const shipped = fs.readFileSync(chartsManifest, 'utf8');
+  const claimed = shipped.replace(
+    'export default {',
+    "export default {\n  providerId: '@astryxdesign/lab',",
+  );
+  expect(claimed).not.toBe(shipped);
+  fs.writeFileSync(chartsManifest, claimed);
+
+  fs.writeFileSync(
+    path.join(consumer, 'package.json'),
+    JSON.stringify({name: 'consumer', private: true}),
+  );
+  fs.writeFileSync(
+    path.join(consumer, 'astryx.config.mjs'),
+    "export default {integrations: ['@astryxdesign/lab', '@astryxdesign/charts']};\n",
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(consumer, {recursive: true, force: true});
+});
+
+describe('provider identity conflicts in the real integration packages', () => {
+  it('keeps Lab, sets Charts aside, and names both on every surface', async () => {
+    const project = await Project.load(consumer, {fresh: true});
+    const components = await project.components();
+    expect(
+      components.filter(component => component.package === '@astryxdesign/lab')
+        .length,
+    ).toBeGreaterThan(0);
+    expect(
+      components.some(component => component.package === '@astryxdesign/charts'),
+    ).toBe(false);
+    const conflicts = (await project.issues()).filter(
+      issue => issue.code === 'duplicate_provider',
+    );
+    expect(conflicts).toEqual([
+      expect.objectContaining({
+        package: expect.stringMatching(/^@astryxdesign\/charts@\S+$/u),
+        severity: 'warning',
+        message: expect.stringMatching(WINNER_NAMED),
+      }),
+    ]);
+
+    const report = await doctor({cwd: consumer});
+    const check = report.data.checks.find(
+      candidate => candidate.id === 'provider-identity',
+    );
+    expect(check?.status).toBe('warn');
+    expect(check?.message).toMatch(WINNER_NAMED);
+
+    const cli = await runCli(['component', '--list'], consumer);
+    expect(cli.status).toBe(0);
+    expect(cli.stderr).toMatch(WINNER_NAMED);
+  }, SLOW);
+
+  it('loads both real packages without an issue once their IDs differ', async () => {
+    fs.copyFileSync(path.join(CHARTS, 'astryx.integration.mjs'), chartsManifest);
+
+    const project = await Project.load(consumer, {fresh: true});
+    const components = await project.components();
+    expect(
+      components.some(component => component.package === '@astryxdesign/charts'),
+    ).toBe(true);
+    expect(
+      (await project.issues()).filter(
+        issue => issue.code === 'duplicate_provider',
+      ),
+    ).toEqual([]);
+  }, SLOW);
+});

package/foundation/integrations/validate-contributions.d.mts

@@ -22,5 +22,7 @@ export function validateLoadedIntegration(loaded: LoadedIntegration): Promise<Is
  */
 /** Stable issue code for an invalid optional agent-doc contribution. */
 export const INVALID_AGENT_DOCS: "invalid_agent_docs";
+/** Stable issue code for a package whose provider ID is already claimed. */
+export const DUPLICATE_PROVIDER: "duplicate_provider";
 export type Issue = import("./issue").AstryxIntegrationIssue;
 export type LoadedIntegration = import("./integrations.mjs").LoadedIntegration;

package/foundation/integrations/validate-contributions.mjs

@@ -39,6 +39,9 @@ import {discoverIntegrationThemes} from '../discovery/theme-discovery.mjs';
 /** Stable issue code for an invalid optional agent-doc contribution. */
 export const INVALID_AGENT_DOCS = 'invalid_agent_docs';
 
+/** Stable issue code for a package whose provider ID is already claimed. */
+export const DUPLICATE_PROVIDER = 'duplicate_provider';
+
 /** @param {string} code @param {string} message @returns {Issue} */
 export function issueError(code, message) {
   return {code, severity: 'error', message};
@@ -289,6 +292,13 @@ export async function validateLoadedIntegration(loaded) {
   /** @type {Issue[]} */
   const issues = [];
   if (!loaded || typeof loaded !== 'object') return issues;
+  // A package set aside for claiming another package's provider ID has no
+  // contribution roots to check; the conflict itself is what to report.
+  if (loaded.__providerConflict) {
+    return [
+      issueWarning(DUPLICATE_PROVIDER, loaded.__providerConflict.message),
+    ];
+  }
   // A manifest that threw on import (or failed the schema) carries a load-error
   // marker and no contribution roots, so every check below would find nothing
   // and report a clean integration — which is how a stale manifest used to go

package/foundation/response/json-contract.test.mjs

@@ -13,6 +13,8 @@
 
 import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {
@@ -27,10 +29,20 @@ import {
 } from './json.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI = path.resolve(__dirname, '..', '..', 'clients', 'cli', 'bin', 'astryx.mjs');
-
-function runCli(args) {
+const CLI = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  'clients',
+  'cli',
+  'bin',
+  'astryx.mjs',
+);
+
+/** @param {string[]} args @param {{cwd?: string}} [options] */
+function runCli(args, {cwd = process.cwd()} = {}) {
   return spawnSync(process.execPath, [CLI, ...args], {
+    cwd,
     encoding: 'utf8',
     timeout: 20_000,
     stdio: ['ignore', 'pipe', 'pipe'],
@@ -42,7 +54,9 @@ describe('json envelope shape', () => {
   let logs;
   beforeEach(() => {
     logs = [];
-    vi.spyOn(console, 'log').mockImplementation((...a) => logs.push(a.join(' ')));
+    vi.spyOn(console, 'log').mockImplementation((...a) =>
+      logs.push(a.join(' ')),
+    );
     setJsonMode(false);
   });
   afterEach(() => {
@@ -80,11 +94,13 @@ describe('json envelope shape', () => {
   });
 
   it('toErrorEnvelope honors an explicit code argument', () => {
-    expect(toErrorEnvelope('boom', undefined, 'ERR_UNKNOWN_COMPONENT')).toEqual({
-      apiVersion: API_VERSION,
-      error: 'boom',
-      code: 'ERR_UNKNOWN_COMPONENT',
-    });
+    expect(toErrorEnvelope('boom', undefined, 'ERR_UNKNOWN_COMPONENT')).toEqual(
+      {
+        apiVersion: API_VERSION,
+        error: 'boom',
+        code: 'ERR_UNKNOWN_COMPONENT',
+      },
+    );
   });
 
   it('toErrorEnvelope reads a code carried on a thrown Error', () => {
@@ -109,8 +125,12 @@ describe('json envelope shape', () => {
     // The guard is `Array.isArray(...) && .length`, not a bare `?.length` — a
     // string ("hello".length === 5) or a `{length: n}` object must NOT slip
     // through as `suggestions`, which is contractually a Suggestion[].
-    expect('suggestions' in toErrorEnvelope('x', /** @type {any} */ ('hello'))).toBe(false);
-    expect('suggestions' in toErrorEnvelope('x', /** @type {any} */ ({length: 3}))).toBe(false);
+    expect(
+      'suggestions' in toErrorEnvelope('x', /** @type {any} */ ('hello')),
+    ).toBe(false);
+    expect(
+      'suggestions' in toErrorEnvelope('x', /** @type {any} */ ({length: 3})),
+    ).toBe(false);
   });
 });
 
@@ -119,8 +139,12 @@ describe('stdout discipline (humanLog / humanWarn)', () => {
   beforeEach(() => {
     logs = [];
     errs = [];
-    vi.spyOn(console, 'log').mockImplementation((...a) => logs.push(a.join(' ')));
-    vi.spyOn(console, 'error').mockImplementation((...a) => errs.push(a.join(' ')));
+    vi.spyOn(console, 'log').mockImplementation((...a) =>
+      logs.push(a.join(' ')),
+    );
+    vi.spyOn(console, 'error').mockImplementation((...a) =>
+      errs.push(a.join(' ')),
+    );
   });
   afterEach(() => {
     vi.restoreAllMocks();
@@ -174,10 +198,15 @@ describe('contract: every --json emission is valid JSON with apiVersion', () =>
   });
 
   it('init emits its install receipt', () => {
-    const r = runCli(['init', '--json']);
-    const env = JSON.parse(r.stdout);
-    expect(env.apiVersion).toBe(API_VERSION);
-    expect(env.type).toBe('init.run');
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-json-contract-'));
+    try {
+      const r = runCli(['init', '--json'], {cwd});
+      const env = JSON.parse(r.stdout);
+      expect(env.apiVersion).toBe(API_VERSION);
+      expect(env.type).toBe('init.run');
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
   });
 
   it('supported command (discover) emits clean JSON, no human chatter leak', () => {