@workpowers/speckle 0.5.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +23 -0
- package/dist/agent-instructions-command.d.ts +23 -0
- package/dist/agent-instructions-command.js +74 -0
- package/dist/agent-instructions-contract.d.ts +120 -0
- package/dist/agent-instructions-contract.js +107 -0
- package/dist/agent-instructions-files.d.ts +31 -0
- package/dist/agent-instructions-files.js +107 -0
- package/dist/cli.d.ts +4 -0
- package/dist/cli.js +11 -0
- package/dist/headers.d.ts +1 -1
- package/dist/headers.js +1 -1
- package/dist/workflow-files.d.ts +2 -0
- package/dist/workflow-files.js +2 -1
- package/dist/workspace.js +9 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -99,6 +99,29 @@ Unavailable live guidance is reported explicitly with any valid cache's revision
|
|
|
99
99
|
and age; a cache is never called current. Server releases carry new guidance;
|
|
100
100
|
restart the router after updating the router package itself.
|
|
101
101
|
|
|
102
|
+
## Put the project's spec in AGENTS.md
|
|
103
|
+
|
|
104
|
+
The bootstrap above says "ask Speckle". The `instructions` command adds what
|
|
105
|
+
THIS project's spec says, for the coding tools that read `AGENTS.md` and never
|
|
106
|
+
call MCP: the project's charter and its Knowledge index (one line per
|
|
107
|
+
perspective, rows as `S-code · name · summary`, pinned rows always present),
|
|
108
|
+
generated from confirmed main with no model and fenced between two markers.
|
|
109
|
+
|
|
110
|
+
```sh
|
|
111
|
+
npx -y @workpowers/speckle instructions # preview the section
|
|
112
|
+
npx -y @workpowers/speckle instructions --apply # write it into AGENTS.md
|
|
113
|
+
npx -y @workpowers/speckle instructions --apply --file CLAUDE.md --file AGENTS.md
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Speckle owns only the text between `<!-- speckle:agent-instructions:begin -->`
|
|
117
|
+
and `<!-- speckle:agent-instructions:end -->`. The file is created when absent,
|
|
118
|
+
the section appended when the file has none, and every byte outside the markers
|
|
119
|
+
is written back unchanged. A `.speckle-instructions.json` receipt beside the
|
|
120
|
+
file records which revision this checkout installed; keep it local. The command
|
|
121
|
+
refuses a section edited since that receipt rather than overwriting it, and it
|
|
122
|
+
is a no-op while the section is current. The section's revision is its content
|
|
123
|
+
hash, independent of the planning and bootstrap revisions. No commits are made.
|
|
124
|
+
|
|
102
125
|
## Diagnosing
|
|
103
126
|
|
|
104
127
|
```bash
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { type AgentInstructionsFile } from "./agent-instructions-contract.js";
|
|
2
|
+
export declare const INSTRUCTIONS_USAGE: string;
|
|
3
|
+
export declare function parseInstructionsArgs(args: string[]): {
|
|
4
|
+
apply: boolean;
|
|
5
|
+
files: AgentInstructionsFile[];
|
|
6
|
+
};
|
|
7
|
+
/** Pull the publication out of a toolbox call result, whichever face it came back on. */
|
|
8
|
+
export declare function parseInstructionsResult(result: {
|
|
9
|
+
isError?: boolean;
|
|
10
|
+
structuredContent?: unknown;
|
|
11
|
+
content?: Array<{
|
|
12
|
+
type: string;
|
|
13
|
+
text?: string;
|
|
14
|
+
}>;
|
|
15
|
+
}): {
|
|
16
|
+
project_id: number;
|
|
17
|
+
revision: string;
|
|
18
|
+
content: string;
|
|
19
|
+
summary: string;
|
|
20
|
+
protocol_version: 1;
|
|
21
|
+
};
|
|
22
|
+
export declare function runInstructionsCommand(args: string[]): Promise<void>;
|
|
23
|
+
//# sourceMappingURL=agent-instructions-command.d.ts.map
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `speckle-mcp instructions [--apply] [--file AGENTS.md|CLAUDE.md]` (I-4367):
|
|
3
|
+
* fetch the project's spec-derived agent instructions from the configured
|
|
4
|
+
* Speckle host and preview or install them as the managed section of
|
|
5
|
+
* AGENTS.md (or CLAUDE.md) at the repository root.
|
|
6
|
+
*
|
|
7
|
+
* Reads only from the authenticated, configured host, over the same MCP
|
|
8
|
+
* client `workflow` uses; the project comes from the `.speckle` marker. The
|
|
9
|
+
* tool is an extended read, so it is reached through `speckle_toolbox`.
|
|
10
|
+
*/
|
|
11
|
+
import path from "node:path";
|
|
12
|
+
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
|
13
|
+
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
|
|
14
|
+
import { loadRouterConfig, resolveSpeckleHost } from "./config.js";
|
|
15
|
+
import { resolveWorkspace, workspaceOptionsFromConfig } from "./workspace.js";
|
|
16
|
+
import { buildRouterHeaders, ROUTER_CLIENT_NAME, ROUTER_CLIENT_VERSION } from "./headers.js";
|
|
17
|
+
import { AGENT_INSTRUCTIONS_FILES, agentInstructionsSchema, isAgentInstructionsFile, } from "./agent-instructions-contract.js";
|
|
18
|
+
import { applyAgentInstructions } from "./agent-instructions-files.js";
|
|
19
|
+
export const INSTRUCTIONS_USAGE = `Usage: speckle-mcp instructions [--apply] [--file ${AGENT_INSTRUCTIONS_FILES.join("|")}]...`;
|
|
20
|
+
export function parseInstructionsArgs(args) {
|
|
21
|
+
const out = { apply: false, files: [] };
|
|
22
|
+
for (let i = 0; i < args.length; i++) {
|
|
23
|
+
const a = args[i];
|
|
24
|
+
if (a === "--apply")
|
|
25
|
+
out.apply = true;
|
|
26
|
+
else if (a === "--file") {
|
|
27
|
+
const v = args[++i];
|
|
28
|
+
if (!v || !isAgentInstructionsFile(v)) {
|
|
29
|
+
throw new Error(`--file takes one of ${AGENT_INSTRUCTIONS_FILES.join(", ")} (got ${JSON.stringify(v ?? "")}). ${INSTRUCTIONS_USAGE}`);
|
|
30
|
+
}
|
|
31
|
+
out.files.push(v);
|
|
32
|
+
}
|
|
33
|
+
else
|
|
34
|
+
throw new Error(INSTRUCTIONS_USAGE);
|
|
35
|
+
}
|
|
36
|
+
return out;
|
|
37
|
+
}
|
|
38
|
+
/** Pull the publication out of a toolbox call result, whichever face it came back on. */
|
|
39
|
+
export function parseInstructionsResult(result) {
|
|
40
|
+
if (result.isError)
|
|
41
|
+
throw new Error("Instructions tool refused retrieval");
|
|
42
|
+
const text = result.content?.find((c) => c.type === "text")?.text;
|
|
43
|
+
const raw = result.structuredContent ?? (text ? JSON.parse(text) : undefined);
|
|
44
|
+
return agentInstructionsSchema.parse(raw);
|
|
45
|
+
}
|
|
46
|
+
export async function runInstructionsCommand(args) {
|
|
47
|
+
const parsed = parseInstructionsArgs(args);
|
|
48
|
+
const config = loadRouterConfig();
|
|
49
|
+
const workspace = resolveWorkspace(workspaceOptionsFromConfig(config));
|
|
50
|
+
const root = path.dirname(workspace.markerPath);
|
|
51
|
+
const host = resolveSpeckleHost(config, workspace.marker.marker.speckleUrl).hostUrl;
|
|
52
|
+
const client = new Client({ name: ROUTER_CLIENT_NAME, version: ROUTER_CLIENT_VERSION }, { capabilities: {} });
|
|
53
|
+
let publication;
|
|
54
|
+
try {
|
|
55
|
+
await client.connect(new StreamableHTTPClientTransport(new URL(`${host}/mcp`), {
|
|
56
|
+
requestInit: { headers: { ...buildRouterHeaders({ apiKey: config.apiKey, workspace }) } },
|
|
57
|
+
}));
|
|
58
|
+
const result = await client.callTool({ name: "speckle_toolbox", arguments: { tool: "get_agent_instructions", arguments: {} } }, undefined, { timeout: 30_000 });
|
|
59
|
+
publication = parseInstructionsResult(result);
|
|
60
|
+
}
|
|
61
|
+
catch (error) {
|
|
62
|
+
const reason = error instanceof Error ? error.message : String(error);
|
|
63
|
+
throw new Error(`Live retrieval of the agent instructions failed (${reason}); no files were written. Retry against a server that serves get_agent_instructions.`);
|
|
64
|
+
}
|
|
65
|
+
finally {
|
|
66
|
+
await client.close().catch(() => undefined);
|
|
67
|
+
}
|
|
68
|
+
if (publication.project_id !== workspace.marker.marker.projectId) {
|
|
69
|
+
throw new Error(`The host answered for project ${publication.project_id}, but the marker names project ${workspace.marker.marker.projectId}; no files were written.`);
|
|
70
|
+
}
|
|
71
|
+
const result = applyAgentInstructions(root, host, publication, { apply: parsed.apply, files: parsed.files });
|
|
72
|
+
process.stdout.write(JSON.stringify(result, null, 2) + "\n");
|
|
73
|
+
}
|
|
74
|
+
//# sourceMappingURL=agent-instructions-command.js.map
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared wire and file contract for the project's AGENTS.md / CLAUDE.md export
|
|
3
|
+
* (I-4367): the section Speckle generates from a project's confirmed spec and
|
|
4
|
+
* the markers that fence it inside a file a person also writes in.
|
|
5
|
+
*
|
|
6
|
+
* Imported by the server (the generator and its REST/MCP faces) and by the CLI
|
|
7
|
+
* (the writer), so the two can never disagree about what the section looks
|
|
8
|
+
* like, which file it goes in, or how its revision is computed.
|
|
9
|
+
*
|
|
10
|
+
* Ownership rule (I-4539's, kept here): Speckle owns ONLY the bytes between
|
|
11
|
+
* the two markers. Everything outside them is the person's and is copied
|
|
12
|
+
* through byte for byte. The revision is the content hash of the section body,
|
|
13
|
+
* separate from the planning and bootstrap revisions, so a spec change never
|
|
14
|
+
* forces a SPECKLE.md diff and a guide release never forces an AGENTS.md diff.
|
|
15
|
+
*/
|
|
16
|
+
import { z } from "zod";
|
|
17
|
+
/** The files the AGENTS.md convention reads; the CLI writes into no other. */
|
|
18
|
+
export declare const AGENT_INSTRUCTIONS_FILES: readonly ["AGENTS.md", "CLAUDE.md"];
|
|
19
|
+
export type AgentInstructionsFile = (typeof AGENT_INSTRUCTIONS_FILES)[number];
|
|
20
|
+
export declare const AGENT_INSTRUCTIONS_DEFAULT_FILE: AgentInstructionsFile;
|
|
21
|
+
/** The per-checkout receipt beside the file; local, never committed. */
|
|
22
|
+
export declare const AGENT_INSTRUCTIONS_RECEIPT_FILE = ".speckle-instructions.json";
|
|
23
|
+
/** The command a person runs to refresh the section. */
|
|
24
|
+
export declare const AGENT_INSTRUCTIONS_COMMAND = "npx -y @workpowers/speckle instructions --apply";
|
|
25
|
+
export declare const AGENT_INSTRUCTIONS_END_MARKER = "<!-- speckle:agent-instructions:end -->";
|
|
26
|
+
/** What the server serves for one project. The CLI validates it before writing. */
|
|
27
|
+
export declare const agentInstructionsSchema: z.ZodEffects<z.ZodObject<{
|
|
28
|
+
protocol_version: z.ZodLiteral<1>;
|
|
29
|
+
project_id: z.ZodNumber;
|
|
30
|
+
/** The section body: what goes between the markers. */
|
|
31
|
+
content: z.ZodString;
|
|
32
|
+
/** `hashContent(content)` — the section's own revision. */
|
|
33
|
+
revision: z.ZodString;
|
|
34
|
+
/** One line on what the section holds, for the preview and the receipt. */
|
|
35
|
+
summary: z.ZodString;
|
|
36
|
+
}, "strip", z.ZodTypeAny, {
|
|
37
|
+
project_id: number;
|
|
38
|
+
revision: string;
|
|
39
|
+
content: string;
|
|
40
|
+
summary: string;
|
|
41
|
+
protocol_version: 1;
|
|
42
|
+
}, {
|
|
43
|
+
project_id: number;
|
|
44
|
+
revision: string;
|
|
45
|
+
content: string;
|
|
46
|
+
summary: string;
|
|
47
|
+
protocol_version: 1;
|
|
48
|
+
}>, {
|
|
49
|
+
project_id: number;
|
|
50
|
+
revision: string;
|
|
51
|
+
content: string;
|
|
52
|
+
summary: string;
|
|
53
|
+
protocol_version: 1;
|
|
54
|
+
}, {
|
|
55
|
+
project_id: number;
|
|
56
|
+
revision: string;
|
|
57
|
+
content: string;
|
|
58
|
+
summary: string;
|
|
59
|
+
protocol_version: 1;
|
|
60
|
+
}>;
|
|
61
|
+
export type AgentInstructions = z.infer<typeof agentInstructionsSchema>;
|
|
62
|
+
/** The local receipt: which revision this checkout installed, per file. */
|
|
63
|
+
export declare const agentInstructionsReceiptSchema: z.ZodObject<{
|
|
64
|
+
protocol_version: z.ZodLiteral<1>;
|
|
65
|
+
host: z.ZodString;
|
|
66
|
+
project_id: z.ZodNumber;
|
|
67
|
+
fetched_at: z.ZodString;
|
|
68
|
+
files: z.ZodRecord<z.ZodEnum<["AGENTS.md", "CLAUDE.md"]>, z.ZodObject<{
|
|
69
|
+
revision: z.ZodString;
|
|
70
|
+
}, "strip", z.ZodTypeAny, {
|
|
71
|
+
revision: string;
|
|
72
|
+
}, {
|
|
73
|
+
revision: string;
|
|
74
|
+
}>>;
|
|
75
|
+
}, "strip", z.ZodTypeAny, {
|
|
76
|
+
project_id: number;
|
|
77
|
+
protocol_version: 1;
|
|
78
|
+
host: string;
|
|
79
|
+
fetched_at: string;
|
|
80
|
+
files: Partial<Record<"AGENTS.md" | "CLAUDE.md", {
|
|
81
|
+
revision: string;
|
|
82
|
+
}>>;
|
|
83
|
+
}, {
|
|
84
|
+
project_id: number;
|
|
85
|
+
protocol_version: 1;
|
|
86
|
+
host: string;
|
|
87
|
+
fetched_at: string;
|
|
88
|
+
files: Partial<Record<"AGENTS.md" | "CLAUDE.md", {
|
|
89
|
+
revision: string;
|
|
90
|
+
}>>;
|
|
91
|
+
}>;
|
|
92
|
+
export type AgentInstructionsReceipt = z.infer<typeof agentInstructionsReceiptSchema>;
|
|
93
|
+
export declare function agentInstructionsBeginMarker(revision: string): string;
|
|
94
|
+
/** The whole managed section: begin marker, body, end marker, each on its own line. */
|
|
95
|
+
export declare function renderAgentInstructionsSection(content: string, revision: string): string;
|
|
96
|
+
export interface ManagedSection {
|
|
97
|
+
/** Character offset of the begin marker line. */
|
|
98
|
+
start: number;
|
|
99
|
+
/** Character offset just past the end marker line (and its newline when present). */
|
|
100
|
+
end: number;
|
|
101
|
+
/** The body between the markers, without the surrounding newlines. */
|
|
102
|
+
body: string;
|
|
103
|
+
/** The revision the begin marker names, when it names one. */
|
|
104
|
+
revision?: string;
|
|
105
|
+
}
|
|
106
|
+
/**
|
|
107
|
+
* Find the managed section in a file's text. `undefined` when the file has
|
|
108
|
+
* none. A begin marker without an end marker, or a second begin marker, is
|
|
109
|
+
* MALFORMED and throws: writing over a file whose fence is broken could eat a
|
|
110
|
+
* person's prose, so the writer refuses instead.
|
|
111
|
+
*/
|
|
112
|
+
export declare function findAgentInstructionsSection(text: string): ManagedSection | undefined;
|
|
113
|
+
/**
|
|
114
|
+
* Put the section into a file's text: replace the existing one in place, or
|
|
115
|
+
* append it (after one blank line) when the file has none. Bytes outside the
|
|
116
|
+
* section are returned exactly as they came in.
|
|
117
|
+
*/
|
|
118
|
+
export declare function replaceAgentInstructionsSection(text: string | undefined, section: string): string;
|
|
119
|
+
export declare function isAgentInstructionsFile(name: string): name is AgentInstructionsFile;
|
|
120
|
+
//# sourceMappingURL=agent-instructions-contract.d.ts.map
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared wire and file contract for the project's AGENTS.md / CLAUDE.md export
|
|
3
|
+
* (I-4367): the section Speckle generates from a project's confirmed spec and
|
|
4
|
+
* the markers that fence it inside a file a person also writes in.
|
|
5
|
+
*
|
|
6
|
+
* Imported by the server (the generator and its REST/MCP faces) and by the CLI
|
|
7
|
+
* (the writer), so the two can never disagree about what the section looks
|
|
8
|
+
* like, which file it goes in, or how its revision is computed.
|
|
9
|
+
*
|
|
10
|
+
* Ownership rule (I-4539's, kept here): Speckle owns ONLY the bytes between
|
|
11
|
+
* the two markers. Everything outside them is the person's and is copied
|
|
12
|
+
* through byte for byte. The revision is the content hash of the section body,
|
|
13
|
+
* separate from the planning and bootstrap revisions, so a spec change never
|
|
14
|
+
* forces a SPECKLE.md diff and a guide release never forces an AGENTS.md diff.
|
|
15
|
+
*/
|
|
16
|
+
import { z } from "zod";
|
|
17
|
+
import { hashContent } from "./workflow-contract.js";
|
|
18
|
+
/** The files the AGENTS.md convention reads; the CLI writes into no other. */
|
|
19
|
+
export const AGENT_INSTRUCTIONS_FILES = ["AGENTS.md", "CLAUDE.md"];
|
|
20
|
+
export const AGENT_INSTRUCTIONS_DEFAULT_FILE = "AGENTS.md";
|
|
21
|
+
/** The per-checkout receipt beside the file; local, never committed. */
|
|
22
|
+
export const AGENT_INSTRUCTIONS_RECEIPT_FILE = ".speckle-instructions.json";
|
|
23
|
+
/** The command a person runs to refresh the section. */
|
|
24
|
+
export const AGENT_INSTRUCTIONS_COMMAND = "npx -y @workpowers/speckle instructions --apply";
|
|
25
|
+
const BEGIN_PREFIX = "<!-- speckle:agent-instructions:begin";
|
|
26
|
+
export const AGENT_INSTRUCTIONS_END_MARKER = "<!-- speckle:agent-instructions:end -->";
|
|
27
|
+
const BEGIN_LINE = /^<!-- speckle:agent-instructions:begin(?: revision=(sha256:[a-f0-9]{64}))? -->[ \t]*$/;
|
|
28
|
+
const END_LINE = /^<!-- speckle:agent-instructions:end -->[ \t]*$/;
|
|
29
|
+
const hash = z.string().regex(/^sha256:[a-f0-9]{64}$/);
|
|
30
|
+
/** What the server serves for one project. The CLI validates it before writing. */
|
|
31
|
+
export const agentInstructionsSchema = z.object({
|
|
32
|
+
protocol_version: z.literal(1),
|
|
33
|
+
project_id: z.number().int().positive(),
|
|
34
|
+
/** The section body: what goes between the markers. */
|
|
35
|
+
content: z.string().min(1).max(200_000),
|
|
36
|
+
/** `hashContent(content)` — the section's own revision. */
|
|
37
|
+
revision: hash,
|
|
38
|
+
/** One line on what the section holds, for the preview and the receipt. */
|
|
39
|
+
summary: z.string().min(1).max(500),
|
|
40
|
+
}).refine((a) => hashContent(a.content) === a.revision, "Content does not match its revision");
|
|
41
|
+
/** The local receipt: which revision this checkout installed, per file. */
|
|
42
|
+
export const agentInstructionsReceiptSchema = z.object({
|
|
43
|
+
protocol_version: z.literal(1),
|
|
44
|
+
host: z.string().url(),
|
|
45
|
+
project_id: z.number().int().positive(),
|
|
46
|
+
fetched_at: z.string().datetime(),
|
|
47
|
+
files: z.record(z.enum(AGENT_INSTRUCTIONS_FILES), z.object({ revision: hash })),
|
|
48
|
+
});
|
|
49
|
+
export function agentInstructionsBeginMarker(revision) {
|
|
50
|
+
return `${BEGIN_PREFIX} revision=${revision} -->`;
|
|
51
|
+
}
|
|
52
|
+
/** The whole managed section: begin marker, body, end marker, each on its own line. */
|
|
53
|
+
export function renderAgentInstructionsSection(content, revision) {
|
|
54
|
+
return `${agentInstructionsBeginMarker(revision)}\n${content.replace(/\s+$/, "")}\n${AGENT_INSTRUCTIONS_END_MARKER}\n`;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Find the managed section in a file's text. `undefined` when the file has
|
|
58
|
+
* none. A begin marker without an end marker, or a second begin marker, is
|
|
59
|
+
* MALFORMED and throws: writing over a file whose fence is broken could eat a
|
|
60
|
+
* person's prose, so the writer refuses instead.
|
|
61
|
+
*/
|
|
62
|
+
export function findAgentInstructionsSection(text) {
|
|
63
|
+
const lines = text.split("\n");
|
|
64
|
+
let start = -1, startLine = -1, revision;
|
|
65
|
+
let offset = 0;
|
|
66
|
+
for (let i = 0; i < lines.length; i++) {
|
|
67
|
+
const line = lines[i];
|
|
68
|
+
const begin = BEGIN_LINE.exec(line);
|
|
69
|
+
if (begin) {
|
|
70
|
+
if (start !== -1)
|
|
71
|
+
throw new Error("AGENTS.md section is malformed: two begin markers. Reconcile it manually; no files were written.");
|
|
72
|
+
start = offset;
|
|
73
|
+
startLine = i;
|
|
74
|
+
revision = begin[1];
|
|
75
|
+
}
|
|
76
|
+
else if (END_LINE.test(line)) {
|
|
77
|
+
if (start === -1)
|
|
78
|
+
throw new Error("AGENTS.md section is malformed: an end marker before any begin marker. Reconcile it manually; no files were written.");
|
|
79
|
+
const endOfLine = offset + line.length;
|
|
80
|
+
const end = text[endOfLine] === "\n" ? endOfLine + 1 : endOfLine;
|
|
81
|
+
const body = lines.slice(startLine + 1, i).join("\n");
|
|
82
|
+
return { start, end, body, revision };
|
|
83
|
+
}
|
|
84
|
+
offset += line.length + 1;
|
|
85
|
+
}
|
|
86
|
+
if (start !== -1)
|
|
87
|
+
throw new Error("AGENTS.md section is malformed: a begin marker with no end marker. Reconcile it manually; no files were written.");
|
|
88
|
+
return undefined;
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* Put the section into a file's text: replace the existing one in place, or
|
|
92
|
+
* append it (after one blank line) when the file has none. Bytes outside the
|
|
93
|
+
* section are returned exactly as they came in.
|
|
94
|
+
*/
|
|
95
|
+
export function replaceAgentInstructionsSection(text, section) {
|
|
96
|
+
if (text === undefined || text === "")
|
|
97
|
+
return section;
|
|
98
|
+
const found = findAgentInstructionsSection(text);
|
|
99
|
+
if (found)
|
|
100
|
+
return text.slice(0, found.start) + section + text.slice(found.end);
|
|
101
|
+
const separator = text.endsWith("\n\n") ? "" : text.endsWith("\n") ? "\n" : "\n\n";
|
|
102
|
+
return text + separator + section;
|
|
103
|
+
}
|
|
104
|
+
export function isAgentInstructionsFile(name) {
|
|
105
|
+
return AGENT_INSTRUCTIONS_FILES.includes(name);
|
|
106
|
+
}
|
|
107
|
+
//# sourceMappingURL=agent-instructions-contract.js.map
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { type AgentInstructions, type AgentInstructionsFile, type AgentInstructionsReceipt } from "./agent-instructions-contract.js";
|
|
2
|
+
export type SectionState = "missing" | "matches_published" | "outdated" | "modified" | "unrecognized";
|
|
3
|
+
export interface FileReport {
|
|
4
|
+
file: AgentInstructionsFile;
|
|
5
|
+
/** Where the section stands before the write. */
|
|
6
|
+
state: SectionState;
|
|
7
|
+
/** Whether this call changed the file. */
|
|
8
|
+
written: boolean;
|
|
9
|
+
}
|
|
10
|
+
export declare function readAgentInstructionsReceipt(root: string, host: string, projectId: number): AgentInstructionsReceipt | undefined;
|
|
11
|
+
/** Where a file's section stands against the publication and the receipt. */
|
|
12
|
+
export declare function observeSection(text: string | undefined, revision: string, baseline: string | undefined): SectionState;
|
|
13
|
+
/**
|
|
14
|
+
* Preview or apply the section into one or more files. Refuses before any
|
|
15
|
+
* write when a file's section is edited or unowned; the receipt advances
|
|
16
|
+
* only after every written file verifies.
|
|
17
|
+
*/
|
|
18
|
+
export declare function applyAgentInstructions(root: string, host: string, input: AgentInstructions, options?: {
|
|
19
|
+
apply?: boolean;
|
|
20
|
+
files?: readonly AgentInstructionsFile[];
|
|
21
|
+
replace?: (file: string, content: string, expected: string | undefined) => void;
|
|
22
|
+
}): {
|
|
23
|
+
applied: boolean;
|
|
24
|
+
project_id: number;
|
|
25
|
+
revision: string;
|
|
26
|
+
summary: string;
|
|
27
|
+
files: FileReport[];
|
|
28
|
+
section: string;
|
|
29
|
+
next_step: string;
|
|
30
|
+
};
|
|
31
|
+
//# sourceMappingURL=agent-instructions-files.d.ts.map
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Explicit, conflict-preserving application of the AGENTS.md / CLAUDE.md
|
|
3
|
+
* section (I-4367) — the managed-section counterpart of workflow-files.ts.
|
|
4
|
+
*
|
|
5
|
+
* The discipline is the one `workflow --apply` set (S-11504): preview by
|
|
6
|
+
* default; bounded regular files only, never a symlink; a per-checkout receipt
|
|
7
|
+
* that says which revision THIS checkout installed; refuse a section that was
|
|
8
|
+
* edited since that receipt rather than overwrite it; and advance the receipt
|
|
9
|
+
* only after the written bytes verify. What differs is the unit of ownership:
|
|
10
|
+
* SPECKLE.md is a whole dedicated file, while here Speckle owns only the text
|
|
11
|
+
* between two markers in a file a person also writes in, so every byte
|
|
12
|
+
* outside the markers is read back and written out unchanged.
|
|
13
|
+
*/
|
|
14
|
+
import path from "node:path";
|
|
15
|
+
import { readManagedFile, replaceManagedFile } from "./workflow-files.js";
|
|
16
|
+
import { hashContent } from "./workflow-contract.js";
|
|
17
|
+
import { AGENT_INSTRUCTIONS_DEFAULT_FILE, AGENT_INSTRUCTIONS_RECEIPT_FILE, agentInstructionsReceiptSchema, agentInstructionsSchema, findAgentInstructionsSection, renderAgentInstructionsSection, replaceAgentInstructionsSection, } from "./agent-instructions-contract.js";
|
|
18
|
+
export function readAgentInstructionsReceipt(root, host, projectId) {
|
|
19
|
+
const raw = readManagedFile(path.join(root, AGENT_INSTRUCTIONS_RECEIPT_FILE));
|
|
20
|
+
if (raw === undefined)
|
|
21
|
+
return undefined;
|
|
22
|
+
const receipt = agentInstructionsReceiptSchema.parse(JSON.parse(raw));
|
|
23
|
+
if (receipt.host !== host)
|
|
24
|
+
throw new Error("Instructions receipt belongs to another Speckle host");
|
|
25
|
+
if (receipt.project_id !== projectId)
|
|
26
|
+
throw new Error("Instructions receipt belongs to another Speckle project");
|
|
27
|
+
if (Date.parse(receipt.fetched_at) > Date.now() + 60_000)
|
|
28
|
+
throw new Error("Instructions receipt has a future timestamp");
|
|
29
|
+
return receipt;
|
|
30
|
+
}
|
|
31
|
+
/** Where a file's section stands against the publication and the receipt. */
|
|
32
|
+
export function observeSection(text, revision, baseline) {
|
|
33
|
+
if (text === undefined)
|
|
34
|
+
return "missing";
|
|
35
|
+
const found = findAgentInstructionsSection(text);
|
|
36
|
+
if (!found)
|
|
37
|
+
return "missing";
|
|
38
|
+
const hash = hashContent(found.body.replace(/\s+$/, "") + "\n");
|
|
39
|
+
if (hash === revision)
|
|
40
|
+
return "matches_published";
|
|
41
|
+
if (!baseline)
|
|
42
|
+
return "unrecognized";
|
|
43
|
+
return hash === baseline ? "outdated" : "modified";
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Preview or apply the section into one or more files. Refuses before any
|
|
47
|
+
* write when a file's section is edited or unowned; the receipt advances
|
|
48
|
+
* only after every written file verifies.
|
|
49
|
+
*/
|
|
50
|
+
export function applyAgentInstructions(root, host, input, options = {}) {
|
|
51
|
+
const publication = agentInstructionsSchema.parse(input);
|
|
52
|
+
const files = options.files && options.files.length > 0 ? [...new Set(options.files)] : [AGENT_INSTRUCTIONS_DEFAULT_FILE];
|
|
53
|
+
const receiptPath = path.join(root, AGENT_INSTRUCTIONS_RECEIPT_FILE);
|
|
54
|
+
const previousReceipt = readManagedFile(receiptPath);
|
|
55
|
+
const previousCache = readAgentInstructionsReceipt(root, host, publication.project_id);
|
|
56
|
+
const section = renderAgentInstructionsSection(publication.content, publication.revision);
|
|
57
|
+
const plan = files.map((file) => {
|
|
58
|
+
const filePath = path.join(root, file);
|
|
59
|
+
const previous = readManagedFile(filePath);
|
|
60
|
+
const state = observeSection(previous, publication.revision, previousCache?.files[file]?.revision);
|
|
61
|
+
if (state === "modified" || state === "unrecognized") {
|
|
62
|
+
throw new Error(`${file}'s Speckle section is edited or unowned. Reconcile it manually; no files were written.`);
|
|
63
|
+
}
|
|
64
|
+
return { file, filePath, previous, state, next: replaceAgentInstructionsSection(previous, section) };
|
|
65
|
+
});
|
|
66
|
+
const receipt = {
|
|
67
|
+
protocol_version: 1,
|
|
68
|
+
host,
|
|
69
|
+
project_id: publication.project_id,
|
|
70
|
+
fetched_at: new Date().toISOString(),
|
|
71
|
+
files: {
|
|
72
|
+
...(previousCache?.files ?? {}),
|
|
73
|
+
...Object.fromEntries(files.map((file) => [file, { revision: publication.revision }])),
|
|
74
|
+
},
|
|
75
|
+
};
|
|
76
|
+
const receiptText = JSON.stringify(receipt, null, 2) + "\n";
|
|
77
|
+
const reports = plan.map((p) => ({ file: p.file, state: p.state, written: false }));
|
|
78
|
+
if (options.apply) {
|
|
79
|
+
const replace = options.replace ?? replaceManagedFile;
|
|
80
|
+
for (const [i, p] of plan.entries()) {
|
|
81
|
+
replace(p.filePath, p.next, p.previous);
|
|
82
|
+
if (readManagedFile(p.filePath) !== p.next)
|
|
83
|
+
throw new Error(`${p.file} verification failed; receipt not advanced`);
|
|
84
|
+
reports[i].written = p.previous !== p.next;
|
|
85
|
+
}
|
|
86
|
+
// The receipt advances only after every installed file verifies.
|
|
87
|
+
replace(receiptPath, receiptText, previousReceipt);
|
|
88
|
+
if (readManagedFile(receiptPath) !== receiptText)
|
|
89
|
+
throw new Error("Instructions receipt did not verify; re-read files before retrying");
|
|
90
|
+
for (const p of plan) {
|
|
91
|
+
if (readManagedFile(p.filePath) !== p.next)
|
|
92
|
+
throw new Error(`${p.file} changed during update; re-read files before retrying`);
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
return {
|
|
96
|
+
applied: Boolean(options.apply),
|
|
97
|
+
project_id: publication.project_id,
|
|
98
|
+
revision: publication.revision,
|
|
99
|
+
summary: publication.summary,
|
|
100
|
+
files: reports,
|
|
101
|
+
section,
|
|
102
|
+
next_step: options.apply
|
|
103
|
+
? `Review the Git diff and commit the section. Keep ${AGENT_INSTRUCTIONS_RECEIPT_FILE} local (a per-checkout receipt). Re-run after the spec changes; the command is a no-op while the section is current.`
|
|
104
|
+
: `Preview only. Run with --apply to write the section into ${files.join(" and ")}; bytes outside the markers are left as they are.`,
|
|
105
|
+
};
|
|
106
|
+
}
|
|
107
|
+
//# sourceMappingURL=agent-instructions-files.js.map
|
package/dist/cli.d.ts
CHANGED
|
@@ -4,6 +4,10 @@
|
|
|
4
4
|
* speckle mcp init --project <id> [--slug <slug>] [--url <speckle_url>]
|
|
5
5
|
* Writes a `.speckle` marker at the repo root.
|
|
6
6
|
*
|
|
7
|
+
* speckle mcp instructions [--apply] [--file AGENTS.md|CLAUDE.md]
|
|
8
|
+
* Fetches the project's spec-derived agent instructions and previews or
|
|
9
|
+
* writes them as the managed section of AGENTS.md (I-4367).
|
|
10
|
+
*
|
|
7
11
|
* speckle mcp doctor
|
|
8
12
|
* Resolves marker + workspace + env and prints a diagnostic
|
|
9
13
|
* summary. Never sends a network request — diagnoses local config
|
package/dist/cli.js
CHANGED
|
@@ -4,6 +4,10 @@
|
|
|
4
4
|
* speckle mcp init --project <id> [--slug <slug>] [--url <speckle_url>]
|
|
5
5
|
* Writes a `.speckle` marker at the repo root.
|
|
6
6
|
*
|
|
7
|
+
* speckle mcp instructions [--apply] [--file AGENTS.md|CLAUDE.md]
|
|
8
|
+
* Fetches the project's spec-derived agent instructions and previews or
|
|
9
|
+
* writes them as the managed section of AGENTS.md (I-4367).
|
|
10
|
+
*
|
|
7
11
|
* speckle mcp doctor
|
|
8
12
|
* Resolves marker + workspace + env and prints a diagnostic
|
|
9
13
|
* summary. Never sends a network request — diagnoses local config
|
|
@@ -17,11 +21,14 @@ import { resolveWorkspace, workspaceOptionsFromConfig } from "./workspace.js";
|
|
|
17
21
|
import { loadRouterConfig, resolveSpeckleHost } from "./config.js";
|
|
18
22
|
import { SpeckleRouterError } from "./errors.js";
|
|
19
23
|
import { runWorkflowCommand } from "./workflow-command.js";
|
|
24
|
+
import { runInstructionsCommand } from "./agent-instructions-command.js";
|
|
20
25
|
export async function runCli(args) {
|
|
21
26
|
const [cmd, ...rest] = args;
|
|
22
27
|
switch (cmd) {
|
|
23
28
|
case "workflow":
|
|
24
29
|
return runWorkflowCommand(rest);
|
|
30
|
+
case "instructions":
|
|
31
|
+
return runInstructionsCommand(rest);
|
|
25
32
|
case "init":
|
|
26
33
|
return runInit(rest);
|
|
27
34
|
case "doctor":
|
|
@@ -154,6 +161,10 @@ function printHelp() {
|
|
|
154
161
|
" speckle-mcp workflow Fetch live guidance and preview dedicated local files.",
|
|
155
162
|
" --apply Apply after ownership checks; review the Git diff.",
|
|
156
163
|
" --cache Also keep planning guidance for explicit offline fallback.",
|
|
164
|
+
" speckle-mcp instructions Fetch the project's spec-derived agent instructions (charter +",
|
|
165
|
+
" Knowledge index with S-codes) and preview the managed AGENTS.md section.",
|
|
166
|
+
" --apply Write only the marked section; bytes outside it stay as they are.",
|
|
167
|
+
" --file <AGENTS.md|CLAUDE.md> Target file (repeatable; default AGENTS.md).",
|
|
157
168
|
" speckle-mcp help Show this message.",
|
|
158
169
|
"",
|
|
159
170
|
"Environment:",
|
package/dist/headers.d.ts
CHANGED
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
*/
|
|
14
14
|
import type { ResolvedWorkspace } from "./workspace.js";
|
|
15
15
|
export declare const ROUTER_CLIENT_NAME = "@workpowers/speckle";
|
|
16
|
-
export declare const ROUTER_CLIENT_VERSION = "0.
|
|
16
|
+
export declare const ROUTER_CLIENT_VERSION = "0.7.0";
|
|
17
17
|
export interface RouterRequestHeaders {
|
|
18
18
|
Authorization: string;
|
|
19
19
|
"X-Speckle-Client": string;
|
package/dist/headers.js
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
* the server then exposes a project-agnostic discovery toolset.
|
|
13
13
|
*/
|
|
14
14
|
export const ROUTER_CLIENT_NAME = "@workpowers/speckle";
|
|
15
|
-
export const ROUTER_CLIENT_VERSION = "0.
|
|
15
|
+
export const ROUTER_CLIENT_VERSION = "0.7.0";
|
|
16
16
|
export function buildRouterHeaders(args) {
|
|
17
17
|
const { apiKey, workspace, fallbackProjectId } = args;
|
|
18
18
|
const headers = {
|
package/dist/workflow-files.d.ts
CHANGED
|
@@ -29,5 +29,7 @@ export declare function applyWorkflowFiles(root: string, host: string, input: Wo
|
|
|
29
29
|
}[];
|
|
30
30
|
next_step: string;
|
|
31
31
|
};
|
|
32
|
+
/** Atomic replace of a managed file, refusing when its bytes moved since the preview. Shared with the AGENTS.md writer (I-4367). */
|
|
33
|
+
export declare function replaceManagedFile(file: string, content: string, expected: string | undefined): void;
|
|
32
34
|
export declare function cachedWorkflowFallback(root: string | undefined, host: string): string;
|
|
33
35
|
//# sourceMappingURL=workflow-files.d.ts.map
|
package/dist/workflow-files.js
CHANGED
|
@@ -105,7 +105,8 @@ export function applyWorkflowFiles(root, host, input, options = {}) {
|
|
|
105
105
|
return { applied: Boolean(options.apply), files,
|
|
106
106
|
next_step: "Review the diff. Add a reference to SPECKLE.md in AGENTS.md/CLAUDE.md after reconciling old Speckle guidance; preserve project conventions. Keep .speckle-workflow.json local (a receipt/optional cache), not a copied planning manual." };
|
|
107
107
|
}
|
|
108
|
-
|
|
108
|
+
/** Atomic replace of a managed file, refusing when its bytes moved since the preview. Shared with the AGENTS.md writer (I-4367). */
|
|
109
|
+
export function replaceManagedFile(file, content, expected) {
|
|
109
110
|
if (readManagedFile(file) !== expected)
|
|
110
111
|
throw new Error("Workflow file changed since preview; retry after reviewing it");
|
|
111
112
|
if (expected === content)
|
package/dist/workspace.js
CHANGED
|
@@ -53,10 +53,16 @@ export function resolveWorkspace(opts = {}) {
|
|
|
53
53
|
}
|
|
54
54
|
const chosen = resolved[0];
|
|
55
55
|
const repoRemote = chosen.marker.parsed.marker.repo?.remote;
|
|
56
|
-
|
|
56
|
+
// Two different questions, previously answered by one branch. WHICH remote
|
|
57
|
+
// this checkout has is always knowable from git, and is what identifies the
|
|
58
|
+
// repository a report came from; whether it MATCHES what the marker claims
|
|
59
|
+
// only applies when the marker claims something. Computing the first only
|
|
60
|
+
// when the second applied meant field markers — which carry version and
|
|
61
|
+
// project_id alone — never produced a remote at all, so nothing downstream
|
|
62
|
+
// could tell two checkouts of one repo from two different repos (I-5126).
|
|
63
|
+
const actual = readGitOriginRemote(chosen.root);
|
|
64
|
+
const canonicalRemote = actual ? canonicalizeGitRemote(actual) : undefined;
|
|
57
65
|
if (repoRemote) {
|
|
58
|
-
const actual = readGitOriginRemote(chosen.root);
|
|
59
|
-
canonicalRemote = actual ? canonicalizeGitRemote(actual) : undefined;
|
|
60
66
|
const expected = canonicalizeGitRemote(repoRemote);
|
|
61
67
|
if (canonicalRemote && expected && canonicalRemote !== expected && !opts.allowRepoMismatch) {
|
|
62
68
|
throw new SpeckleRouterError("marker_remote_mismatch", `.speckle belongs to ${expected}, but this checkout appears to be ${canonicalRemote}.`, "If this is intentional, set SPECKLE_MCP_ALLOW_REPO_MISMATCH=1 to bypass.", { expected, actual: canonicalRemote, markerPath: chosen.marker.markerPath });
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@workpowers/speckle",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "Local MCP router for Speckle — resolves project context from a committed .speckle marker and forwards calls to the remote Speckle MCP endpoint.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|