Skip to content

Commit 0bb9289

Browse files
harbournickharbournick
authored
refactor(document-api): remove unused tool manifest artifact pipeline (#2406)
* refactor(document-api): remove unused tool manifest artifact pipeline * refactor(cli): remove unused intentName field from CLI-only operation definitions
1 parent b014618 commit 0bb9289

9 files changed

Lines changed: 19 additions & 142 deletions

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,7 @@ These directories are produced by `pnpm run generate:all`:
136136

137137
| Directory | In git? | What it contains |
138138
|-----------|---------|-----------------|
139-
| `packages/document-api/generated/` | No (gitignored) | Agent tool schemas, JSON schemas, manifest |
139+
| `packages/document-api/generated/` | No (gitignored) | Agent artifacts, JSON schemas |
140140
| `apps/cli/generated/` | No (gitignored) | SDK contract JSON exported from CLI metadata |
141141
| `packages/sdk/langs/node/src/generated/` | No (gitignored) | Node SDK generated client code |
142142
| `packages/sdk/langs/python/superdoc/generated/` | No (gitignored) | Python SDK generated client code |

‎apps/cli/src/cli/__tests__/cli-only-definitions.test.ts‎

Lines changed: 0 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -57,12 +57,6 @@ describe('CLI-only operation definitions', () => {
5757
}
5858
});
5959

60-
test('all CLI-only ops have non-empty intentName', () => {
61-
for (const [, def] of Object.entries(CLI_ONLY_OPERATION_DEFINITIONS)) {
62-
expect(def.intentName).toBeTruthy();
63-
}
64-
});
65-
6660
test('sdkMetadata fields present and correctly typed', () => {
6761
const validIdempotency = new Set(['idempotent', 'non-idempotent', 'conditional']);
6862

@@ -112,23 +106,3 @@ describe('CLI-only outputSchema validity', () => {
112106
}
113107
});
114108
});
115-
116-
// ---------------------------------------------------------------------------
117-
// Intent name naming policy
118-
// ---------------------------------------------------------------------------
119-
120-
describe('CLI-only intent name naming policy', () => {
121-
test('all intentNames match snake_case naming policy', () => {
122-
for (const [, def] of Object.entries(CLI_ONLY_OPERATION_DEFINITIONS)) {
123-
expect(def.intentName).toMatch(/^[a-z][a-z0-9_]*$/);
124-
}
125-
});
126-
127-
test('all intentNames are unique', () => {
128-
const seen = new Set<string>();
129-
for (const [, def] of Object.entries(CLI_ONLY_OPERATION_DEFINITIONS)) {
130-
expect(seen.has(def.intentName)).toBe(false);
131-
seen.add(def.intentName);
132-
}
133-
});
134-
});

‎apps/cli/src/cli/cli-only-operation-definitions.ts‎

Lines changed: 1 addition & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
* views they need from this canonical object:
77
*
88
* - operation-set.ts → category, description, tokens, requiresDoc
9-
* - export-sdk-contract.ts → intentName, sdkMetadata, outputSchema
9+
* - export-sdk-contract.ts → sdkMetadata, outputSchema
1010
* - response-schemas.ts → CLI-only response schema entries
1111
*/
1212

@@ -28,7 +28,6 @@ export interface CliOnlyOperationDefinition {
2828
description: string;
2929
requiresDocumentContext: boolean;
3030
tokenOverride?: readonly string[];
31-
intentName: string;
3231
sdkMetadata: CliOnlySdkMetadata;
3332
outputSchema: Record<string, unknown>;
3433
/** When true, this operation is excluded from generated LLM tool catalogs. */
@@ -45,7 +44,6 @@ export const CLI_ONLY_OPERATION_DEFINITIONS: Record<CliOnlyOperation, CliOnlyOpe
4544
description:
4645
'Open a document and create a persistent editing session. Optionally override the document body with contentOverride + overrideType (markdown, html, or text).',
4746
requiresDocumentContext: false,
48-
intentName: 'open_document',
4947
sdkMetadata: { mutates: true, idempotency: 'non-idempotent', supportsTrackedMode: false, supportsDryRun: false },
5048
outputSchema: {
5149
type: 'object',
@@ -88,7 +86,6 @@ export const CLI_ONLY_OPERATION_DEFINITIONS: Record<CliOnlyOperation, CliOnlyOpe
8886
category: 'session',
8987
description: 'Save the current session to the original file or a new path.',
9088
requiresDocumentContext: false,
91-
intentName: 'save_document',
9289
sdkMetadata: { mutates: true, idempotency: 'conditional', supportsTrackedMode: false, supportsDryRun: false },
9390
outputSchema: {
9491
type: 'object',
@@ -127,7 +124,6 @@ export const CLI_ONLY_OPERATION_DEFINITIONS: Record<CliOnlyOperation, CliOnlyOpe
127124
category: 'session',
128125
description: 'Close the active editing session and clean up resources.',
129126
requiresDocumentContext: false,
130-
intentName: 'close_document',
131127
sdkMetadata: { mutates: true, idempotency: 'conditional', supportsTrackedMode: false, supportsDryRun: false },
132128
outputSchema: {
133129
type: 'object',
@@ -154,7 +150,6 @@ export const CLI_ONLY_OPERATION_DEFINITIONS: Record<CliOnlyOperation, CliOnlyOpe
154150
category: 'session',
155151
description: 'Show the current session status and document metadata.',
156152
requiresDocumentContext: false,
157-
intentName: 'get_status',
158153
sdkMetadata: { mutates: false, idempotency: 'idempotent', supportsTrackedMode: false, supportsDryRun: false },
159154
outputSchema: {
160155
type: 'object',
@@ -194,7 +189,6 @@ export const CLI_ONLY_OPERATION_DEFINITIONS: Record<CliOnlyOperation, CliOnlyOpe
194189
category: 'session',
195190
description: 'List all available CLI operations and contract metadata.',
196191
requiresDocumentContext: false,
197-
intentName: 'describe_commands',
198192
skipAsATool: true,
199193
sdkMetadata: { mutates: false, idempotency: 'idempotent', supportsTrackedMode: false, supportsDryRun: false },
200194
outputSchema: {
@@ -222,7 +216,6 @@ export const CLI_ONLY_OPERATION_DEFINITIONS: Record<CliOnlyOperation, CliOnlyOpe
222216
description: 'Show detailed metadata for a single CLI operation.',
223217
requiresDocumentContext: false,
224218
tokenOverride: ['describe', 'command'],
225-
intentName: 'describe_command',
226219
skipAsATool: true,
227220
sdkMetadata: { mutates: false, idempotency: 'idempotent', supportsTrackedMode: false, supportsDryRun: false },
228221
outputSchema: {
@@ -242,7 +235,6 @@ export const CLI_ONLY_OPERATION_DEFINITIONS: Record<CliOnlyOperation, CliOnlyOpe
242235
category: 'session',
243236
description: 'List all active editing sessions.',
244237
requiresDocumentContext: false,
245-
intentName: 'list_sessions',
246238
sdkMetadata: { mutates: false, idempotency: 'idempotent', supportsTrackedMode: false, supportsDryRun: false },
247239
outputSchema: {
248240
type: 'object',
@@ -268,7 +260,6 @@ export const CLI_ONLY_OPERATION_DEFINITIONS: Record<CliOnlyOperation, CliOnlyOpe
268260
category: 'session',
269261
description: 'Persist the current session state.',
270262
requiresDocumentContext: false,
271-
intentName: 'save_session',
272263
sdkMetadata: { mutates: true, idempotency: 'conditional', supportsTrackedMode: false, supportsDryRun: false },
273264
outputSchema: {
274265
type: 'object',
@@ -300,7 +291,6 @@ export const CLI_ONLY_OPERATION_DEFINITIONS: Record<CliOnlyOperation, CliOnlyOpe
300291
category: 'session',
301292
description: 'Close a specific editing session by ID.',
302293
requiresDocumentContext: false,
303-
intentName: 'close_session',
304294
sdkMetadata: { mutates: true, idempotency: 'conditional', supportsTrackedMode: false, supportsDryRun: false },
305295
outputSchema: {
306296
type: 'object',
@@ -328,7 +318,6 @@ export const CLI_ONLY_OPERATION_DEFINITIONS: Record<CliOnlyOperation, CliOnlyOpe
328318
category: 'session',
329319
description: 'Set the default session for subsequent commands.',
330320
requiresDocumentContext: false,
331-
intentName: 'set_default_session',
332321
sdkMetadata: { mutates: true, idempotency: 'conditional', supportsTrackedMode: false, supportsDryRun: false },
333322
outputSchema: {
334323
type: 'object',

‎packages/document-api/scripts/README.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,10 @@ Do not hand-edit generated output files. Regenerate instead.
3232

3333
| Script | Kind | Purpose | Reads | Writes | Typical caller |
3434
| --- | --- | --- | --- | --- | --- |
35-
| `check-contract-outputs.ts` | check | Full generated-output gate across schemas/manifests/agent/reference + overview block | Contract snapshot + generated roots + docs overview | None | CI/local full verification |
36-
| `generate-contract-outputs.ts` | generate | Full regeneration across schemas/manifests/agent/reference + overview block | Contract snapshot + docs overview | `packages/document-api/generated/*`, `apps/docs/document-api/reference/*`, generated block in overview | Main local sync before commit |
35+
| `check-contract-outputs.ts` | check | Full generated-output gate across schemas/agent/reference + overview block | Contract snapshot + generated roots + docs overview | None | CI/local full verification |
36+
| `generate-contract-outputs.ts` | generate | Full regeneration across schemas/agent/reference + overview block | Contract snapshot + docs overview | `packages/document-api/generated/*`, `apps/docs/document-api/reference/*`, generated block in overview | Main local sync before commit |
3737
| `check-stable-schemas.ts` | check | Validate stable schema artifact drift | Contract snapshot + `packages/document-api/generated/schemas` | None | Focused check during schema work |
3838
| `generate-stable-schemas.ts` | generate | Regenerate stable schema artifacts | Contract snapshot | `packages/document-api/generated/schemas/*` | Focused schema regeneration |
39-
| `check-tool-manifests.ts` | check | Validate tool manifest artifact drift | Contract snapshot + `packages/document-api/generated/manifests` | None | Focused manifest check |
40-
| `generate-tool-manifests.ts` | generate | Regenerate tool manifest artifacts | Contract snapshot | `packages/document-api/generated/manifests/*` | Focused manifest regeneration |
4139
| `check-agent-artifacts.ts` | check | Validate agent artifact drift | Contract snapshot + `packages/document-api/generated/agent` | None | Focused agent-artifact check |
4240
| `generate-agent-artifacts.ts` | generate | Regenerate agent artifacts (remediation/workflow/compatibility) | Contract snapshot | `packages/document-api/generated/agent/*` | Focused agent-artifact regeneration |
4341
| `check-generated-reference-docs.ts` | check | Validate generated reference docs and overview generated block drift | Contract snapshot + `apps/docs/document-api/reference` + overview | None | Focused docs generation check |

‎packages/document-api/scripts/check-contract-outputs.ts‎

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,15 @@
11
/**
22
* Purpose: Verify all contract-derived outputs are up to date.
33
* Caller: Main CI/local gate for generated Document API artifacts.
4-
* Reads: Contract snapshot + generated schemas/manifests/agent artifacts/reference docs + overview.
4+
* Reads: Contract snapshot + generated schemas/agent artifacts/reference docs + overview.
55
* Writes: None (exit code + console output only).
66
* Fails when: Any generated output is missing/extra/stale or overview block is out of sync.
77
*/
88
import {
99
buildStableSchemaArtifacts,
10-
buildToolManifestArtifacts,
1110
buildAgentArtifacts,
1211
getAgentArtifactRoot,
1312
getStableSchemaRoot,
14-
getToolManifestRoot,
1513
} from './lib/contract-output-artifacts.js';
1614
import { checkGeneratedFiles, formatGeneratedCheckIssues, runScript } from './lib/generation-utils.js';
1715
import {
@@ -21,15 +19,10 @@ import {
2119
} from './lib/reference-docs-artifacts.js';
2220

2321
runScript('contract output artifacts check', async () => {
24-
const files = [
25-
...buildStableSchemaArtifacts(),
26-
...buildToolManifestArtifacts(),
27-
...buildAgentArtifacts(),
28-
...buildReferenceDocsArtifacts(),
29-
];
22+
const files = [...buildStableSchemaArtifacts(), ...buildAgentArtifacts(), ...buildReferenceDocsArtifacts()];
3023

3124
const issues = await checkGeneratedFiles(files, {
32-
roots: [getStableSchemaRoot(), getToolManifestRoot(), getAgentArtifactRoot(), getReferenceDocsOutputRoot()],
25+
roots: [getStableSchemaRoot(), getAgentArtifactRoot(), getReferenceDocsOutputRoot()],
3326
});
3427

3528
await checkReferenceDocsExtras(files, issues);

‎packages/document-api/scripts/check-tool-manifests.ts‎

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎packages/document-api/scripts/generate-contract-outputs.ts‎

Lines changed: 12 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2,26 +2,24 @@
22
* Purpose: Generate all contract-derived outputs in one pass.
33
* Caller: Main local sync command before committing contract/docs changes.
44
* Reads: Contract snapshot + existing overview doc markers/content.
5-
* Writes: Stable schemas, tool manifests, agent artifacts, reference docs, and overview generated block.
5+
* Writes: Stable schemas, agent artifacts, reference docs, and overview generated block.
66
* Output: Deterministic generated files aligned to the current contract.
77
*/
8-
import {
9-
buildStableSchemaArtifacts,
10-
buildToolManifestArtifacts,
11-
buildAgentArtifacts,
12-
} from './lib/contract-output-artifacts.js';
8+
import { rm } from 'node:fs/promises';
9+
import { buildStableSchemaArtifacts, buildAgentArtifacts } from './lib/contract-output-artifacts.js';
1310
import { buildReferenceDocsArtifacts, buildOverviewArtifact } from './lib/reference-docs-artifacts.js';
14-
import { runScript, writeGeneratedFiles } from './lib/generation-utils.js';
11+
import { resolveWorkspacePath, runScript, writeGeneratedFiles } from './lib/generation-utils.js';
12+
13+
/** Directories from removed artifact types that may still exist in developer workspaces. */
14+
const DEPRECATED_OUTPUT_DIRS = ['packages/document-api/generated/manifests'];
1515

1616
runScript('generate contract outputs', async () => {
17+
await Promise.all(
18+
DEPRECATED_OUTPUT_DIRS.map((dir) => rm(resolveWorkspacePath(dir), { recursive: true, force: true })),
19+
);
20+
1721
const overview = await buildOverviewArtifact();
18-
const files = [
19-
...buildStableSchemaArtifacts(),
20-
...buildToolManifestArtifacts(),
21-
...buildAgentArtifacts(),
22-
...buildReferenceDocsArtifacts(),
23-
overview,
24-
];
22+
const files = [...buildStableSchemaArtifacts(), ...buildAgentArtifacts(), ...buildReferenceDocsArtifacts(), overview];
2523

2624
await writeGeneratedFiles(files);
2725
console.log(`generated contract outputs (${files.length} files, including overview block)`);

‎packages/document-api/scripts/generate-tool-manifests.ts‎

Lines changed: 0 additions & 11 deletions
This file was deleted.

‎packages/document-api/scripts/lib/contract-output-artifacts.ts‎

Lines changed: 0 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,9 @@
11
import { buildContractSnapshot } from './contract-snapshot.js';
22
import { stableStringify, type GeneratedFile } from './generation-utils.js';
3-
import { OPERATION_EXPECTED_RESULT_MAP } from '../../src/index.js';
43

54
const GENERATED_FILE_HEADER = 'GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`.\n';
65

76
const STABLE_SCHEMA_ROOT = 'packages/document-api/generated/schemas';
8-
const TOOL_MANIFEST_ROOT = 'packages/document-api/generated/manifests';
97
const AGENT_ARTIFACT_ROOT = 'packages/document-api/generated/agent';
108

119
function buildOperationContractMap() {
@@ -61,51 +59,6 @@ export function buildStableSchemaArtifacts(): GeneratedFile[] {
6159
];
6260
}
6361

64-
function toToolDescription(operationId: string, mutates: boolean): string {
65-
if (mutates) {
66-
return `Apply Document API mutation \`${operationId}\`.`;
67-
}
68-
return `Read Document API data via \`${operationId}\`.`;
69-
}
70-
71-
export function buildToolManifestArtifacts(): GeneratedFile[] {
72-
const contractMap = buildOperationContractMap();
73-
74-
const tools = Object.entries(contractMap.operations).map(([operationId, operation]) => ({
75-
name: operationId,
76-
memberPath: operation.memberPath,
77-
description: toToolDescription(operationId, operation.metadata.mutates),
78-
expectedResult: OPERATION_EXPECTED_RESULT_MAP[operationId as keyof typeof OPERATION_EXPECTED_RESULT_MAP],
79-
mutates: operation.metadata.mutates,
80-
idempotency: operation.metadata.idempotency,
81-
supportsTrackedMode: operation.metadata.supportsTrackedMode,
82-
supportsDryRun: operation.metadata.supportsDryRun,
83-
deterministicTargetResolution: operation.metadata.deterministicTargetResolution,
84-
preApplyThrows: operation.metadata.throws.preApply,
85-
possibleFailureCodes: operation.metadata.possibleFailureCodes,
86-
remediationHints: operation.metadata.remediationHints ?? [],
87-
inputSchema: operation.inputSchema,
88-
outputSchema: operation.outputSchema,
89-
successSchema: operation.successSchema,
90-
failureSchema: operation.failureSchema,
91-
}));
92-
93-
const manifest = {
94-
contractVersion: contractMap.contractVersion,
95-
sourceHash: contractMap.sourceHash,
96-
generatedAt: null,
97-
sourceCommit: null,
98-
tools,
99-
};
100-
101-
return [
102-
{
103-
path: `${TOOL_MANIFEST_ROOT}/document-api-tools.json`,
104-
content: stableStringify(manifest),
105-
},
106-
];
107-
}
108-
10962
const DEFAULT_REMEDIATION_BY_CODE: Record<string, string> = {
11063
TARGET_NOT_FOUND: 'Refresh targets via find/get operations and retry with a fresh address or ID.',
11164
CAPABILITY_UNAVAILABLE: 'Check runtime capabilities and switch to supported mode or operation.',
@@ -254,10 +207,6 @@ export function getStableSchemaRoot(): string {
254207
return STABLE_SCHEMA_ROOT;
255208
}
256209

257-
export function getToolManifestRoot(): string {
258-
return TOOL_MANIFEST_ROOT;
259-
}
260-
261210
export function getAgentArtifactRoot(): string {
262211
return AGENT_ARTIFACT_ROOT;
263212
}

0 commit comments

Comments
 (0)