Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): init --remove-agents says when there was nothing to remove (#6623)

Joey0c4c661d38cf
diff --git a/.changeset/cli-init-remove-reports-nothing-to-remove.md b/.changeset/cli-init-remove-reports-nothing-to-remove.md
new file mode 100644
index 0000000000..68d64664e3
--- /dev/null
+++ b/.changeset/cli-init-remove-reports-nothing-to-remove.md
@@ -0,0 +1,11 @@
+---
+'@astryxdesign/cli': minor
+---
+
+[breaking] `init --remove-agents` says when there was nothing to remove.
+
+- incompatible-fix `IFIX-0004` / cleanup `CLN-0010`
+
+Migration: a consumer reading `data.removed` as a boolean keeps working; a consumer that narrowed on the literal `true` sees the corrected value.
+
+@josephfarina
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 49419feaef..30fd688a0e 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -423,7 +423,7 @@ Every response has a `type` discriminant. The full set is below (generated from
| Type | What `data` carries |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `init.run` | The install receipt: the `mode` (`default` \| `features`), the features run, agent-doc files written, any soft `docsError`, whether theme guidance was emitted, the template outcome (`workflow` \| `created` \| `skipped`) plus its path, and whether the next-steps were emitted. |
-| `init.remove` | Confirmation that the managed agent-docs block was removed (`data.removed: true`) — returned when --remove-agents is set. |
+| `init.remove` | The removal receipt — returned when --remove-agents is set: `data.removed` is true when a managed agent-docs block was found and removed, and false when there was none to remove. |
| `component.list` | The component catalog grouped by component group (each component's group field): `detail` (the level: names \| compact \| full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries ({name, package, description, import}), or a full ComponentDoc per entry with its package. |
| `component.batch` | The component specialization of the shared `BatchResponse` and `BatchRow` types. An explicit programmatic selector array, or two or more CLI selectors, returns one ordered receipt: `count` plus `results`, one row per selector including duplicates. Every row carries `selector` and `status` (found \| not_found \| ambiguous \| error). A found row carries `result`, the same {type, data} response as one selector. An ambiguous row carries `code`, `error`, and `candidates` ({package, component, kind, installed}). Other failed rows carry `code`, `error`, and optional `suggestions` ({name, reason}). |
| `component.detail` | One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc). The envelope's package names the same owner. |
diff --git a/packages/cli/api/init/init.doc.mjs b/packages/cli/api/init/init.doc.mjs
index 2f2d38b2f9..1c1c82f807 100644
--- a/packages/cli/api/init/init.doc.mjs
+++ b/packages/cli/api/init/init.doc.mjs
@@ -76,10 +76,14 @@ export const doc = {
{
type: 'init.remove',
description:
- 'Returned when `removeAgents` is set. `data.removed` is always true, even when no managed block was found.',
+ 'The removal receipt, returned when `removeAgents` is set: `data.removed` is true when a managed agent-docs block was found and removed, and false when there was none to remove.',
},
],
throws: [
+ {
+ code: 'ERR_INVALID_ARGUMENT',
+ when: '--remove-agents is combined with --features, --all, --agent, or --agent-docs-path; or --all is combined with --features',
+ },
{
code: 'ERR_UNKNOWN_AGENT',
when: 'the agents feature runs (default mode, features includes agents, or all) and `agent` is not one of claude, cursor, codex, hermes, muse, all',
diff --git a/packages/cli/api/init/init.type.mjs b/packages/cli/api/init/init.type.mjs
index 2cf6fb2746..ad7c7ef636 100644
--- a/packages/cli/api/init/init.type.mjs
+++ b/packages/cli/api/init/init.type.mjs
@@ -29,7 +29,7 @@
/**
* @typedef {object} InitRemoveResponse
* @property {'init.remove'} type
- * @property {{removed: true}} data
+ * @property {{removed: boolean}} data False when no managed agent-docs block was found, so nothing was removed.
*/
/**
diff --git a/packages/cli/api/init/remove/remove.mjs b/packages/cli/api/init/remove/remove.mjs
index 89c84e3d29..32ef048436 100644
--- a/packages/cli/api/init/remove/remove.mjs
+++ b/packages/cli/api/init/remove/remove.mjs
@@ -23,7 +23,12 @@ import {logger} from '../../logger.mjs';
* @returns {Promise<import('../init.type.mjs').InitRemoveResponse>}
*/
export async function remove({cwd = process.cwd()} = {}) {
- removeAgentDocs(cwd);
- logger.log('[ok] AI agent docs removed.');
- return {type: 'init.remove', data: {removed: true}};
+ const removedFrom = removeAgentDocs(cwd);
+ const removed = removedFrom.length > 0;
+ logger.log(
+ removed
+ ? '[ok] AI agent docs removed.'
+ : '[ok] Nothing to remove: no Astryx agent-docs block was found.',
+ );
+ return {type: 'init.remove', data: {removed}};
}
diff --git a/packages/cli/api/init/remove/remove.test.mjs b/packages/cli/api/init/remove/remove.test.mjs
new file mode 100644
index 0000000000..a0d92dc3b0
--- /dev/null
+++ b/packages/cli/api/init/remove/remove.test.mjs
@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import * as fs from 'node:fs'; import * as path from 'node:path';
+import {init} from '../init.mjs'; import {remove} from './remove.mjs'; import {logger} from '../../logger.mjs';
+let dir;
+beforeEach(() => { dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-rm-')); fs.writeFileSync(path.join(dir,'package.json'),JSON.stringify({name:'c',version:'1.0.0'})); });
+afterEach(() => { fs.rmSync(dir,{recursive:true,force:true}); logger.setSilent(true); });
+describe('init.remove says whether anything was removed', () => {
+ it('false on clean', async () => { const r=await remove({cwd:dir}); expect(r.type).toBe('init.remove'); expect(r.data.removed).toBe(false); });
+ it('true then false', async () => { await init({features:['agents']},{cwd:dir}); expect(fs.readFileSync(path.join(dir,'AGENTS.md'),'utf8')).toContain('<!-- ASTRYX:START -->'); const a=await remove({cwd:dir}); expect(a.data.removed).toBe(true); const b=await remove({cwd:dir}); expect(b.data.removed).toBe(false); });
+ it('human line', async () => { const l=[]; const s=vi.spyOn(console,'log').mockImplementation((...a)=>l.push(a.join(' '))); logger.setSilent(false); try{await remove({cwd:dir});}finally{logger.setSilent(true);s.mockRestore();} expect(l.join('\n')).toContain('Nothing to remove'); });
+});
diff --git a/packages/cli/foundation/agent-docs/agent-docs.mjs b/packages/cli/foundation/agent-docs/agent-docs.mjs
index 192b21a3da..5ca6f4fbe4 100644
--- a/packages/cli/foundation/agent-docs/agent-docs.mjs
+++ b/packages/cli/foundation/agent-docs/agent-docs.mjs
@@ -773,6 +773,7 @@ function assertTargetsWithin(targetDir, relPaths) {
/**
* Remove Astryx section from all known agent doc files.
* @param {string} targetDir
+ * @returns {string[]} the project-relative files a block was removed from.
* @throws {PathSafetyError} `ERR_PATH_TRAVERSAL` when a file it would change
* resolves outside `targetDir`; nothing is changed.
*/
@@ -789,11 +790,14 @@ export function removeAgentDocs(targetDir) {
throw new PathSafetyError(err.message, ERROR_CODES.ERR_PATH_TRAVERSAL);
}
+ /** @type {string[]} */
+ const removedFrom = [];
for (const p of allPaths) {
const filePath = path.join(targetDir, p);
// Delete if empty for files we created (AGENTS.md, .claude/CLAUDE.md)
const deleteIfEmpty = p === AGENTS_MD || p === CLAUDE_DIR_MD;
if (removeXdsBlock(filePath, {deleteIfEmpty})) {
+ removedFrom.push(p);
if (!fs.existsSync(filePath)) {
humanLog(`[ok] Removed empty ${p}`);
} else {
@@ -801,6 +805,7 @@ export function removeAgentDocs(targetDir) {
}
}
}
+ return removedFrom;
}
/**
diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjs
index 2a2bee8fac..e8d9edf76d 100644
--- a/packages/cli/foundation/response/response-types.doc.mjs
+++ b/packages/cli/foundation/response/response-types.doc.mjs
@@ -30,7 +30,7 @@ export const doc = {
{
value: 'init.remove',
description:
- 'Confirmation that the managed agent-docs block was removed (`data.removed: true`) — returned when --remove-agents is set.',
+ 'The removal receipt — returned when --remove-agents is set: `data.removed` is true when a managed agent-docs block was found and removed, and false when there was none to remove.',
},
// component
{