@namewta/speculo 0.6.1 → 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 +7 -10
- package/dist/src/cli.js +36 -128
- package/dist/src/cli.js.map +1 -1
- package/dist/src/index.d.ts +2 -4
- package/dist/src/index.js +151 -165
- package/dist/src/index.js.map +1 -1
- package/package.json +4 -3
- package/template/.speculo/README.md +4 -0
- package/template/skills/github-npm-ops/references/preflight-checklist.md +1 -1
- package/template/workflows/specdev/I-init-setup/I-init-setup.md +1 -1
- package/dist/src/migrate.d.ts +0 -51
- package/dist/src/migrate.js +0 -939
- package/dist/src/migrate.js.map +0 -1
- package/dist/src/skills-mirror.d.ts +0 -38
- package/dist/src/skills-mirror.js +0 -160
- package/dist/src/skills-mirror.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @namewta/speculo
|
|
2
2
|
|
|
3
|
-
> Workflow-packaged specification-driven development assets with
|
|
3
|
+
> Workflow-packaged specification-driven development assets with direct refresh tooling.
|
|
4
4
|
|
|
5
5
|
Speculo packages AI coding workflows as installable assets — commands, skills, workflow packages — delivered into any project via a unified CLI.
|
|
6
6
|
|
|
@@ -10,12 +10,9 @@ Speculo packages AI coding workflows as installable assets — commands, skills,
|
|
|
10
10
|
# Initialize Speculo in a target project
|
|
11
11
|
npx @namewta/speculo init
|
|
12
12
|
|
|
13
|
-
# Install all workflow packages
|
|
14
|
-
npx @namewta/speculo init --all
|
|
15
|
-
|
|
16
13
|
# Global install
|
|
17
14
|
npm install -g @namewta/speculo
|
|
18
|
-
speculo init [
|
|
15
|
+
speculo init [target]
|
|
19
16
|
```
|
|
20
17
|
|
|
21
18
|
After initialization, the target project's `speculo/` directory contains all core assets and selected workflow packages.
|
|
@@ -32,10 +29,10 @@ Requires: Node.js ≥ 22.22.3
|
|
|
32
29
|
|
|
33
30
|
| Command | Description |
|
|
34
31
|
|---|---|
|
|
35
|
-
| `speculo init [
|
|
36
|
-
| `speculo
|
|
37
|
-
|
|
38
|
-
|
|
32
|
+
| `speculo` / `speculo init [target]` | Initialize or directly refresh the managed Speculo assets. Each refresh replaces `config.json`, workspace metadata, commands, skills, and selected workflow packages with the current template. For selected workflows it resets managed state while retaining only `changes/` and `archive/`; command Markdown reports remain, but command `state.json` files are removed. Existing supported workflows not selected in the prompt remain untouched. Projects with SpecDev installed also get an idempotent `specdev-worktree/` entry in the project-root `.gitignore`. |
|
|
33
|
+
| `speculo version` | Print the installed version and check npm for the latest release. |
|
|
34
|
+
|
|
35
|
+
Legacy `migrate`, `mirror-skills`, and `update` commands, plus their flags, were removed in v0.7.0. Re-run `speculo init` to refresh old installations; no compatibility migration is performed.
|
|
39
36
|
|
|
40
37
|
## Installed Runtime Assets
|
|
41
38
|
|
|
@@ -89,7 +86,7 @@ Speculo stands on the shoulders of pioneers — including our own failures. With
|
|
|
89
86
|
- **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** — a lightweight spec-driven development framework whose changes/ directory structure and archive mechanism deeply influenced Speculo's persistence contract design.
|
|
90
87
|
- **[Superpowers](https://github.com/obra/superpowers)** — a complete agentic development methodology whose skill orchestration and subagent dispatch provided key reference for workflow package design.
|
|
91
88
|
|
|
92
|
-
Speculo synthesizes lessons from all: from failure we learned "documents are the interface"; from Matt we inherited skill methodology; from OpenSpec we adopted engineering management; from Superpowers we studied orchestration. Together they form package-based workflow management, persistence contracts, and a
|
|
89
|
+
Speculo synthesizes lessons from all: from failure we learned "documents are the interface"; from Matt we inherited skill methodology; from OpenSpec we adopted engineering management; from Superpowers we studied orchestration. Together they form package-based workflow management, persistence contracts, and a direct refresh lifecycle. We carry their spirit forward.
|
|
93
90
|
|
|
94
91
|
## License
|
|
95
92
|
|
package/dist/src/cli.js
CHANGED
|
@@ -2,30 +2,18 @@
|
|
|
2
2
|
import { dirname, resolve } from "node:path";
|
|
3
3
|
import { fileURLToPath } from "node:url";
|
|
4
4
|
import { initSpeculo } from "./index.js";
|
|
5
|
-
import {
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
import { checkForUpdate, formatVersionBanner } from "./version.js";
|
|
6
|
+
const REMOVED_COMMANDS = new Set(["migrate", "mirror-skills", "update"]);
|
|
7
|
+
const REMOVED_OPTIONS = new Set(["--all", "--apply", "--dry-run"]);
|
|
8
8
|
function usage() {
|
|
9
9
|
return [
|
|
10
10
|
"Usage:",
|
|
11
|
-
" speculo init
|
|
12
|
-
" speculo migrate [--apply] [target]",
|
|
13
|
-
" speculo mirror-skills [--dry-run] [target]",
|
|
11
|
+
" speculo [init] [target]",
|
|
14
12
|
" speculo version",
|
|
15
13
|
"",
|
|
16
14
|
"Commands:",
|
|
17
|
-
" init
|
|
18
|
-
"
|
|
19
|
-
" migrate Preview migration from v2, transitional v3, or SpecDev status v3 state.",
|
|
20
|
-
" Pass --apply to perform the staged, rollback-safe migration.",
|
|
21
|
-
" mirror-skills Mirror .agents/skills/* canonical skills into .claude/skills/* pointers.",
|
|
22
|
-
" Idempotent; relocates full .claude skills into .agents canonical first.",
|
|
23
|
-
" version Print the current Speculo version and check for updates.",
|
|
24
|
-
"",
|
|
25
|
-
"Options:",
|
|
26
|
-
" --all Select every workflow and fully refresh all assets during init.",
|
|
27
|
-
" --apply Apply a migration; without this flag migrate is always dry-run.",
|
|
28
|
-
" --dry-run Preview mirror-skills actions without writing to disk.",
|
|
15
|
+
" init Install or directly refresh Speculo assets and selected workflow packages.",
|
|
16
|
+
" version Print the current Speculo version and check for updates.",
|
|
29
17
|
].join("\n");
|
|
30
18
|
}
|
|
31
19
|
function isInteractive() {
|
|
@@ -37,132 +25,52 @@ async function showVersionWithCheck(packageRoot, packageName) {
|
|
|
37
25
|
return info;
|
|
38
26
|
}
|
|
39
27
|
async function confirmContinue() {
|
|
40
|
-
if (!isInteractive())
|
|
28
|
+
if (!isInteractive())
|
|
41
29
|
return true;
|
|
42
|
-
}
|
|
43
30
|
const { confirm } = await import("@inquirer/prompts");
|
|
44
|
-
return confirm({
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
31
|
+
return confirm({ message: "是否继续运行 speculo init？", default: true });
|
|
32
|
+
}
|
|
33
|
+
function assertNoRemovedOption(argv) {
|
|
34
|
+
const option = argv.find((argument) => REMOVED_OPTIONS.has(argument));
|
|
35
|
+
if (option)
|
|
36
|
+
throw new Error(option + " has been removed. Run speculo init [target] to refresh Speculo.");
|
|
48
37
|
}
|
|
49
38
|
async function main(argv) {
|
|
50
|
-
|
|
51
|
-
const applyFlag = argv.includes("--apply");
|
|
52
|
-
const dryRunFlag = argv.includes("--dry-run");
|
|
53
|
-
const positional = argv.filter((argument) => argument !== "--all" &&
|
|
54
|
-
argument !== "--apply" &&
|
|
55
|
-
argument !== "--dry-run");
|
|
56
|
-
const [command, targetArg, extra] = positional;
|
|
57
|
-
if (command === "--help" || command === "-h") {
|
|
39
|
+
if (argv[0] === "--help" || argv[0] === "-h") {
|
|
58
40
|
console.log(usage());
|
|
59
41
|
return 0;
|
|
60
42
|
}
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
console.error(
|
|
43
|
+
const [command, ...rest] = argv;
|
|
44
|
+
if (command && REMOVED_COMMANDS.has(command)) {
|
|
45
|
+
console.error("speculo " + command + " has been removed. Run speculo init [target] to refresh Speculo.");
|
|
64
46
|
return 1;
|
|
65
47
|
}
|
|
66
|
-
const target = resolve(targetArg ?? ".");
|
|
67
|
-
const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
|
|
68
|
-
const packageName = "@namewta/speculo";
|
|
69
48
|
try {
|
|
70
|
-
|
|
49
|
+
assertNoRemovedOption(argv);
|
|
50
|
+
const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
|
|
51
|
+
const packageName = "@namewta/speculo";
|
|
71
52
|
if (command === "version") {
|
|
53
|
+
if (rest.length > 0)
|
|
54
|
+
throw new Error("speculo version does not accept arguments.");
|
|
72
55
|
await showVersionWithCheck(packageRoot, packageName);
|
|
73
56
|
return 0;
|
|
74
57
|
}
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
if (!proceed) {
|
|
85
|
-
console.log("已取消。");
|
|
86
|
-
return 0;
|
|
87
|
-
}
|
|
88
|
-
const result = await initSpeculo(targetArg ?? ".", {
|
|
89
|
-
packageRoot,
|
|
90
|
-
all: command === "init" ? allFlag : false,
|
|
91
|
-
});
|
|
92
|
-
console.log(result.mode === "init"
|
|
93
|
-
? "Speculo initialized in " + result.target
|
|
94
|
-
: "Speculo updated in " + result.target);
|
|
95
|
-
for (const item of result.copied ?? result.updated ?? []) {
|
|
96
|
-
console.log(" " + (result.mode === "init" ? "copied " : "updated ") + item);
|
|
97
|
-
}
|
|
98
|
-
return 0;
|
|
99
|
-
}
|
|
100
|
-
// ── migrate ──────────────────────────────────────────────
|
|
101
|
-
if (command === "migrate") {
|
|
102
|
-
if (allFlag) {
|
|
103
|
-
throw new Error("--all is only valid with `speculo init`.");
|
|
104
|
-
}
|
|
105
|
-
const result = await migrateSpeculo(target, {
|
|
106
|
-
packageRoot,
|
|
107
|
-
apply: applyFlag,
|
|
108
|
-
});
|
|
109
|
-
if (!result.legacyDetected) {
|
|
110
|
-
console.log("No Speculo state migration required in " + result.target);
|
|
111
|
-
return 0;
|
|
112
|
-
}
|
|
113
|
-
console.log(result.applied
|
|
114
|
-
? "Speculo state migrated in " + result.target
|
|
115
|
-
: "Speculo migration preview for " + result.target);
|
|
116
|
-
for (const action of result.actions) {
|
|
117
|
-
const mapping = action.from
|
|
118
|
-
? action.from + (action.to ? " -> " + action.to : "")
|
|
119
|
-
: action.detail;
|
|
120
|
-
console.log(" " + action.kind + " " + mapping);
|
|
121
|
-
}
|
|
122
|
-
if (!result.applied) {
|
|
123
|
-
console.log("Dry-run only. Re-run with --apply to perform this migration.");
|
|
124
|
-
}
|
|
58
|
+
const targetArg = command === "init" ? rest[0] : command;
|
|
59
|
+
const extra = command === "init" ? rest[1] : rest[0];
|
|
60
|
+
if (extra)
|
|
61
|
+
throw new Error("Unexpected argument: " + extra);
|
|
62
|
+
if (targetArg?.startsWith("-"))
|
|
63
|
+
throw new Error("Unknown option: " + targetArg);
|
|
64
|
+
await showVersionWithCheck(packageRoot, packageName);
|
|
65
|
+
if (!(await confirmContinue())) {
|
|
66
|
+
console.log("已取消。");
|
|
125
67
|
return 0;
|
|
126
68
|
}
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
if (applyFlag) {
|
|
133
|
-
throw new Error("--apply is only valid with `speculo migrate`.");
|
|
134
|
-
}
|
|
135
|
-
const result = await mirrorSkills(targetArg ?? ".", {
|
|
136
|
-
apply: !dryRunFlag,
|
|
137
|
-
});
|
|
138
|
-
console.log(result.applied
|
|
139
|
-
? "Skills mirrored in " + result.target
|
|
140
|
-
: "Skills mirror preview for " + result.target);
|
|
141
|
-
for (const action of result.actions) {
|
|
142
|
-
console.log(" " + action.kind + " " + action.name +
|
|
143
|
-
(action.detail ? " (" + action.detail + ")" : ""));
|
|
144
|
-
}
|
|
145
|
-
if (result.actions.length === 0) {
|
|
146
|
-
console.log(" No skills found under .agents/skills or .claude/skills.");
|
|
147
|
-
}
|
|
148
|
-
if (!result.applied) {
|
|
149
|
-
console.log("Dry-run only. Re-run without --dry-run to apply.");
|
|
150
|
-
}
|
|
151
|
-
return 0;
|
|
152
|
-
}
|
|
153
|
-
// ── update (deprecated) ──────────────────────────────────
|
|
154
|
-
if (command === "update") {
|
|
155
|
-
console.error("Warning: `speculo update` is deprecated. Use `speculo init`.");
|
|
156
|
-
const result = await initSpeculo(target, {
|
|
157
|
-
packageRoot,
|
|
158
|
-
all: true,
|
|
159
|
-
});
|
|
160
|
-
console.log("Speculo updated in " + result.target);
|
|
161
|
-
return 0;
|
|
162
|
-
}
|
|
163
|
-
console.error("Unknown command: " + command);
|
|
164
|
-
console.error(usage());
|
|
165
|
-
return 1;
|
|
69
|
+
const result = await initSpeculo(targetArg ?? ".", { packageRoot });
|
|
70
|
+
console.log(result.mode === "init" ? "Speculo initialized in " + result.target : "Speculo refreshed in " + result.target);
|
|
71
|
+
for (const asset of result.assets)
|
|
72
|
+
console.log(" refreshed " + asset);
|
|
73
|
+
return 0;
|
|
166
74
|
}
|
|
167
75
|
catch (error) {
|
|
168
76
|
console.error(error instanceof Error ? error.message : String(error));
|
package/dist/src/cli.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;
|
|
1
|
+
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}
|
package/dist/src/index.d.ts
CHANGED
|
@@ -1,13 +1,11 @@
|
|
|
1
1
|
import { type WorkflowSelection } from "./workflows.js";
|
|
2
2
|
export type SpeculoCommandResult = {
|
|
3
3
|
target: string;
|
|
4
|
-
mode: "init" | "
|
|
5
|
-
|
|
6
|
-
updated?: string[];
|
|
4
|
+
mode: "init" | "refresh";
|
|
5
|
+
assets: string[];
|
|
7
6
|
};
|
|
8
7
|
export type SpeculoOptions = {
|
|
9
8
|
packageRoot?: string;
|
|
10
|
-
all?: boolean;
|
|
11
9
|
selection?: WorkflowSelection;
|
|
12
10
|
};
|
|
13
11
|
export declare function initSpeculo(targetArg?: string, options?: SpeculoOptions): Promise<SpeculoCommandResult>;
|