@agent-ix/quoin 0.5.0 → 0.5.2

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.
@@ -4,41 +4,41 @@ import { fileURLToPath as l } from "node:url";
4
4
  import { configureRuntimeContext as u, runSelfUpdate as d } from "@agent-ix/ix-cli-core";
5
5
  import { homedir as f } from "node:os";
6
6
  import { parse as p } from "yaml";
7
- import { installEntry as ee, readRegistry as m, reconcile as h, validateMarketplaceManifest as te, writeRegistry as g } from "@agent-ix/ts-plugin-kit";
8
- import { spawn as _ } from "node:child_process";
7
+ import { installEntry as ee, readRegistry as m, reconcile as h, validateMarketplaceManifest as te, writeRegistry as ne } from "@agent-ix/ts-plugin-kit";
8
+ import { spawn as re } from "node:child_process";
9
9
  //#region src/catalog.ts
10
- function v() {
10
+ function g() {
11
11
  return process.env.IX_HOME && process.env.IX_HOME.length > 0 ? process.env.IX_HOME : s(f(), ".ix");
12
12
  }
13
- function y(e = v()) {
13
+ function _(e = g()) {
14
14
  return s(e, "filament", "modules");
15
15
  }
16
- function b(t = v()) {
16
+ function v(t = g()) {
17
17
  let r = [], i = process.env.QUOIN_MODULE_PATHS;
18
18
  i && r.push(...i.split(":").filter(Boolean));
19
- let a = y(t);
19
+ let a = _(t);
20
20
  if (e(a)) for (let e of n(a)) r.push(s(a, e));
21
21
  return r;
22
22
  }
23
- function x(e = b()) {
23
+ function y(e = v()) {
24
24
  let n = [], r = [], i = /* @__PURE__ */ new Set(), o = /* @__PURE__ */ new Set();
25
25
  for (let c of e) {
26
- let e = ne(c);
26
+ let e = ie(c);
27
27
  if (!e || i.has(e)) continue;
28
28
  i.add(e);
29
- let l = p(t(s(e, "manifest.yaml"), "utf8")), u = E(l.name) ?? a(e);
29
+ let l = p(t(s(e, "manifest.yaml"), "utf8")), u = w(l.name) ?? a(e);
30
30
  if (o.has(u)) continue;
31
31
  o.add(u);
32
- let d = T(l.artifact_types), f = T(l.object_types);
32
+ let d = C(l.artifact_types), f = C(l.object_types);
33
33
  n.push({
34
34
  name: u,
35
- version: E(l.version),
35
+ version: w(l.version),
36
36
  root: e,
37
37
  artifactTypes: d.map((e) => String(e.name)),
38
38
  objectTypes: f.map((e) => String(e.name))
39
39
  });
40
40
  for (let t of d) {
41
- let n = String(t.name), i = E(t.frontmatter_schema_ref);
41
+ let n = String(t.name), i = w(t.frontmatter_schema_ref);
42
42
  r.push({
43
43
  name: n,
44
44
  kind: "artifact",
@@ -46,7 +46,7 @@ function x(e = b()) {
46
46
  moduleRoot: e,
47
47
  schemaRef: i,
48
48
  schemaPath: i ? s(e, i) : void 0,
49
- skeletonPath: w(e, n)
49
+ skeletonPath: S(e, n)
50
50
  });
51
51
  }
52
52
  for (let t of f) {
@@ -56,24 +56,24 @@ function x(e = b()) {
56
56
  kind: "object",
57
57
  moduleName: u,
58
58
  moduleRoot: e,
59
- skeletonPath: w(e, n)
59
+ skeletonPath: S(e, n)
60
60
  });
61
61
  }
62
62
  }
63
63
  return {
64
64
  modules: n,
65
65
  entries: r,
66
- duplicates: D(r)
66
+ duplicates: T(r)
67
67
  };
68
68
  }
69
- function S(e, t) {
70
- let n = C(t);
71
- return e.entries.find((e) => C(e.name) === n);
69
+ function b(e, t) {
70
+ let n = x(t);
71
+ return e.entries.find((e) => x(e.name) === n);
72
72
  }
73
- function C(e) {
73
+ function x(e) {
74
74
  return e.toLowerCase();
75
75
  }
76
- function ne(t) {
76
+ function ie(t) {
77
77
  let r = c(t);
78
78
  if (e(r)) {
79
79
  if (e(s(r, "manifest.yaml"))) return r;
@@ -83,16 +83,16 @@ function ne(t) {
83
83
  }
84
84
  }
85
85
  }
86
- function w(t, n) {
86
+ function S(t, n) {
87
87
  return [s(t, "skeletons", `${n}.md`), s(t, "skeletons", `${n.toLowerCase()}.md`)].find((t) => e(t));
88
88
  }
89
- function T(e) {
89
+ function C(e) {
90
90
  return Array.isArray(e) ? e.filter((e) => !!e && typeof e == "object" && "name" in e) : [];
91
91
  }
92
- function E(e) {
92
+ function w(e) {
93
93
  return typeof e == "string" ? e : void 0;
94
94
  }
95
- function D(e) {
95
+ function T(e) {
96
96
  let t = /* @__PURE__ */ new Map();
97
97
  for (let n of e) {
98
98
  let e = `${n.kind}:${n.name}`, r = t.get(e) ?? /* @__PURE__ */ new Set();
@@ -109,19 +109,19 @@ function D(e) {
109
109
  }
110
110
  //#endregion
111
111
  //#region src/plugins.ts
112
- function O(e = v()) {
112
+ function E(e = g()) {
113
113
  return s(e, "filament", "registry.json");
114
114
  }
115
- function k(e) {
115
+ function D(e) {
116
116
  return {
117
117
  cacheRoot: s(e, "cache", "ts-plugin-kit"),
118
- targetRoot: y(e),
119
- registryPath: O(e),
120
- readName: P,
118
+ targetRoot: _(e),
119
+ registryPath: E(e),
120
+ readName: M,
121
121
  materialize: "copy"
122
122
  };
123
123
  }
124
- function A(e) {
124
+ function O(e) {
125
125
  if (e.startsWith("path:")) return {
126
126
  type: "path",
127
127
  path: e.slice(5)
@@ -155,23 +155,23 @@ function A(e) {
155
155
  path: e
156
156
  };
157
157
  }
158
- function j(e, t = v()) {
159
- return ee({ source: A(e) }, k(t));
158
+ function k(e, t = g()) {
159
+ return ee({ source: O(e) }, D(t));
160
160
  }
161
- function M(e = v()) {
162
- return m(O(e)).plugins;
161
+ function A(e = g()) {
162
+ return m(E(e)).plugins;
163
163
  }
164
- function N(e, t = v()) {
165
- let n = m(O(t));
166
- r(s(y(t), e), {
164
+ function j(e, t = g()) {
165
+ let n = m(E(t));
166
+ r(s(_(t), e), {
167
167
  force: !0,
168
168
  recursive: !0
169
- }), g(O(t), {
169
+ }), ne(E(t), {
170
170
  schemaVersion: 1,
171
171
  plugins: n.plugins.filter((t) => t.name !== e)
172
172
  });
173
173
  }
174
- function P(n) {
174
+ function M(n) {
175
175
  let r = e(s(n, "manifest.yaml")) ? s(n, "manifest.yaml") : s(n, a(n), "manifest.yaml");
176
176
  if (!e(r)) throw Error(`no manifest.yaml found under ${n}`);
177
177
  let i = p(t(r, "utf8"));
@@ -180,21 +180,21 @@ function P(n) {
180
180
  }
181
181
  //#endregion
182
182
  //#region src/modules.ts
183
- function F() {
183
+ function N() {
184
184
  return o(o(l(import.meta.url)));
185
185
  }
186
- function I() {
187
- return te(p(t(s(F(), "default-modules.yaml"), "utf8")));
186
+ function P() {
187
+ return te(p(t(s(N(), "default-modules.yaml"), "utf8")));
188
188
  }
189
- function L(e = v(), t = I()) {
189
+ function F(e = g(), t = P()) {
190
190
  h(t, {
191
- ...k(e),
191
+ ...D(e),
192
192
  mode: "lazy"
193
193
  });
194
194
  }
195
195
  //#endregion
196
196
  //#region src/flows.ts
197
- var R = {
197
+ var I = {
198
198
  review: {
199
199
  packageSkill: "spec-review",
200
200
  runtimeSkill: "review"
@@ -208,11 +208,11 @@ var R = {
208
208
  runtimeSkill: "to-plan"
209
209
  }
210
210
  };
211
- function z() {
212
- return Object.keys(R);
211
+ function L() {
212
+ return Object.keys(I);
213
213
  }
214
- async function B(e, t = {}) {
215
- let n = V(e), r = v(), i = [
214
+ async function R(e, t = {}) {
215
+ let n = z(e), r = g(), i = [
216
216
  "run",
217
217
  e,
218
218
  "--path",
@@ -224,14 +224,14 @@ async function B(e, t = {}) {
224
224
  ];
225
225
  t.id && i.push("--id", t.id), t.json && i.push("--json");
226
226
  for (let e of t.target ?? []) i.push("--target", e);
227
- await U(i);
227
+ await V(i);
228
228
  }
229
- function V(t) {
230
- let n = R[t];
229
+ function z(t) {
230
+ let n = I[t];
231
231
  if (!n) throw Error(`unknown spec flow ${t}`);
232
232
  let r = [
233
233
  process.env.IX_SPEC_WORKFLOWS_ROOT,
234
- H(),
234
+ B(),
235
235
  s(o(c(process.cwd())), "ix-spec-workflows"),
236
236
  s(f(), ".ix", "plugins", "ix-spec-workflows")
237
237
  ].filter((e) => !!e);
@@ -241,12 +241,12 @@ function V(t) {
241
241
  }
242
242
  throw Error(`could not find ix-spec workflow skill ${n.runtimeSkill}; set IX_SPEC_WORKFLOWS_ROOT`);
243
243
  }
244
- function H() {
244
+ function B() {
245
245
  return s(o(o(l(import.meta.url))), "skills");
246
246
  }
247
- async function U(e) {
247
+ async function V(e) {
248
248
  await new Promise((t, n) => {
249
- let r = _("ix-flow", e, { stdio: "inherit" });
249
+ let r = re("ix-flow", e, { stdio: "inherit" });
250
250
  r.on("error", n), r.on("close", (e) => {
251
251
  if (e === 0) {
252
252
  t();
@@ -258,28 +258,28 @@ async function U(e) {
258
258
  }
259
259
  //#endregion
260
260
  //#region src/write.ts
261
- function W(e) {
261
+ function H(e) {
262
262
  return (Array.isArray(e) ? e : e ? [e] : []).flatMap((e) => e.split(",")).map((e) => e.trim()).filter(Boolean);
263
263
  }
264
- function G(t, n, r) {
264
+ function U(t, n, r) {
265
265
  if (r.length === 0) throw Error("write requires --types <type[,type...]>");
266
266
  let a = c(n);
267
267
  if (!e(a) || !i(a).isDirectory()) throw Error(`write repo_dir is not a directory: ${n}`);
268
268
  return {
269
269
  repoRoot: a,
270
270
  types: r.map((e) => {
271
- let n = S(t, e);
271
+ let n = b(t, e);
272
272
  if (!n) throw Error(`catalog type not found: ${e}\nAvailable types: ${t.entries.map((e) => e.name).sort((e, t) => e.localeCompare(t)).join(", ")}`);
273
- return q(n);
273
+ return G(n);
274
274
  }),
275
275
  validation: {
276
- command: `quire validate --scope ${J(a)} "spec/**/*.md"`,
276
+ command: `quire validate --scope ${K(a)} "spec/**/*.md"`,
277
277
  scope: a,
278
278
  globs: ["spec/**/*.md"]
279
279
  }
280
280
  };
281
281
  }
282
- function K(e) {
282
+ function W(e) {
283
283
  let t = [
284
284
  "quoin write",
285
285
  "",
@@ -290,7 +290,7 @@ function K(e) {
290
290
  for (let n of e.types) t.push(`- ${n.name} (${n.kind})`), t.push(` module: ${n.moduleName}`), t.push(` module_root: ${n.moduleRoot}`), n.skeletonPath && t.push(` skeleton: ${n.skeletonPath}`), n.schemaPath && t.push(` schema: ${n.schemaPath}`), !n.skeletonPath && !n.schemaPath && t.push(" contract: manifest only");
291
291
  return t.push(""), t.push("Author files directly in the repo, then validate changed spec files."), t.push(`Validate scope: ${e.validation.scope}`), t.push(`Validate command: ${e.validation.command}`), t.join("\n");
292
292
  }
293
- function q(e) {
293
+ function G(e) {
294
294
  return {
295
295
  name: e.name,
296
296
  kind: e.kind,
@@ -300,70 +300,76 @@ function q(e) {
300
300
  ...e.skeletonPath ? { skeletonPath: e.skeletonPath } : {}
301
301
  };
302
302
  }
303
- function J(e) {
303
+ function K(e) {
304
304
  return /^[A-Za-z0-9_./:-]+$/.test(e) ? e : `'${e.replaceAll("'", "'\\''")}'`;
305
305
  }
306
306
  //#endregion
307
307
  //#region src/cli.ts
308
- var Y = "quoin\n\nSpec workflow and catalog CLI for Agent IX.\n\nquoin starts spec-domain work. ix-flow resumes, advances, acknowledges gates,\nand inspects workflow runs created by quoin.\n\nDefault modules (installed on first use into ~/.ix/filament/modules):\n Artifact modules: spec-artifacts-iso, spec-artifacts-app, spec-artifacts-process\n Object modules: spec-objects-business, spec-objects-architecture,\n spec-objects-enterprise, spec-objects-operational,\n spec-objects-security\n Workflows: review, matrix, to-plan\n\nUsage:\n quoin write <repo_dir> --types <type[,type...]>\n quoin catalog list|validate\n quoin catalog show <type>\n quoin plugin install <path:...|github:...>\n quoin plugin list\n quoin plugin remove <name>\n quoin review|matrix|to-plan [--target <ref>...]\n quoin update [--check] [--registry <url>]\n\nGlobal flags:\n --json\n --config-root <dir> Defaults to ~/.ix\n\nExamples:\n quoin catalog list\n quoin catalog show FR\n quoin plugin install github:agent-ix/spec-objects-custom\n quoin write . --types FR,domain\n ix-flow status <run-id>\n", X = "quoin write\n\nBuild an authoring pack for spec files an agent is about to create or edit.\n\nPass the target repository and the artifact/object types involved in the work.\nquoin resolves those types from the active catalog and returns the local\nskeletons, schemas, module roots, and Quire validation command for the repo.\n\nUsage:\n quoin write <repo_dir> --types <type[,type...]>\n\nExamples:\n quoin write . --types FR\n quoin write . --types FR,domain,entity\n quoin write ../my-service --types fr,DOMAIN --json\n\nNotes:\n - Type lookup is case-insensitive; FR and fr are the same type.\n - Types can be artifacts or objects from the default module set or plugins.\n - Use the returned skeletons and schemas as the authoring contract.\n - Run the returned Quire command after editing spec files.\n", re = "quoin catalog\n\nInspect the active artifact/object catalog.\n\nThe catalog is assembled from, in order:\n 1. QUOIN_MODULE_PATHS\n 2. modules installed under ~/.ix/filament/modules\n\nThe default module set is installed there automatically on first catalog access,\nand updated by \"quoin plugin install\". The same directory is read by quire-rs.\n\nDefault artifact modules:\n spec-artifacts-iso FR, NFR, StR, US, IT, TC, AC, CON, Spec\n spec-artifacts-app app-level artifacts\n spec-artifacts-process plans, reviews, matrices, ADRs, tasks, findings\n\nDefault object modules:\n spec-objects-business\n spec-objects-architecture\n spec-objects-enterprise\n spec-objects-operational\n spec-objects-security\n\nUsage:\n quoin catalog list\n quoin catalog show <type>\n quoin catalog validate\n\nExamples:\n quoin catalog show FR\n quoin catalog show entity\n quoin catalog validate --json\n", ie = "quoin plugin\n\nInstall and manage user/community spec modules.\n\nPlugins add or override artifact/object modules under ~/.ix/filament/modules.\nUse \"catalog list\" to see the full active catalog, including default modules and\nplugins.\n\nSupported install sources:\n path:<dir> Use a local directory containing manifest.yaml\n github:<owner>/<repo> Clone a GitHub repository (manifest at root)\n github:<owner>/<repo>@<ref> Pin to a tag, branch, or sha\n github:<owner>/<repo>//<subdir> Manifest in a monorepo subdirectory (@<ref> ok)\n\nUsage:\n quoin plugin install <path:...|github:...>\n quoin plugin list\n quoin plugin remove <name>\n quoin plugin ensure-defaults\n\nExamples:\n quoin plugin install path:../spec-objects-custom\n quoin plugin install github:agent-ix/spec-objects-custom\n quoin plugin install github:agent-ix/spec-objects-security//spec_objects_security@v0.1.1\n quoin plugin list\n quoin plugin ensure-defaults\n", ae = "quoin update\n\nCheck for and install the latest published quoin.\n\nquoin is distributed on the public npm registry as @agent-ix/quoin. This command\nqueries the registry for the latest version, compares it to the running version,\nand (unless --check) runs npm install -g to upgrade in place.\n\nUsage:\n quoin update [--check] [--registry <url>]\n\nFlags:\n --check Report whether an update is available; do not install.\n --registry <url> Force an npm registry to query/install from. Defaults\n to your npm config (the registry @agent-ix resolves to,\n i.e. however quoin was installed). Pass\n https://registry.npmjs.org/ for public npm, or\n http://npm.ix/ for local dev snapshots.\n\nExamples:\n quoin update\n quoin update --check\n quoin update --registry http://npm.ix/\n", oe = "quoin workflows\n\nStart bundled spec review/planning workflows. quoin creates the workflow run in ~/.ix/flows.\nUse ix-flow to inspect, resume, advance phases, and acknowledge human gates.\n\nAvailable workflow launchers:\n review Run a composite spec review\n matrix Build or update a requirements test matrix\n to-plan Convert accepted requirements into an implementation plan\n\nUsage:\n quoin review|matrix|to-plan [--target <ref>...]\n\nExamples:\n quoin review --target spec/\n quoin matrix --target spec/\n ix-flow status <run-id>\n ix-flow resume <run-id>\n";
309
- async function se(e) {
310
- let t = pe(e);
308
+ var q = "https://registry.npmjs.org/", J = "quoin\n\nSpec workflow and catalog CLI for Agent IX.\n\nquoin starts spec-domain work. ix-flow resumes, advances, acknowledges gates,\nand inspects workflow runs created by quoin.\n\nDefault modules (installed on first use into ~/.ix/filament/modules):\n Artifact modules: spec-artifacts-iso, spec-artifacts-app, spec-artifacts-process\n Object modules: spec-objects-business, spec-objects-architecture,\n spec-objects-enterprise, spec-objects-operational,\n spec-objects-security\n Workflows: review, matrix, to-plan\n\nUsage:\n quoin write <repo_dir> --types <type[,type...]>\n quoin catalog list|validate\n quoin catalog show <type>\n quoin plugin install <path:...|github:...>\n quoin plugin list\n quoin plugin remove <name>\n quoin review|matrix|to-plan [--target <ref>...]\n quoin update [--check] [--registry <url>]\n\nGlobal flags:\n --json\n --config-root <dir> Defaults to ~/.ix\n\nExamples:\n quoin catalog list\n quoin catalog show FR\n quoin plugin install github:agent-ix/spec-objects-custom\n quoin write . --types FR,domain\n ix-flow status <run-id>\n", Y = "quoin write\n\nBuild an authoring pack for spec files an agent is about to create or edit.\n\nPass the target repository and the artifact/object types involved in the work.\nquoin resolves those types from the active catalog and returns the local\nskeletons, schemas, module roots, and Quire validation command for the repo.\n\nUsage:\n quoin write <repo_dir> --types <type[,type...]>\n\nExamples:\n quoin write . --types FR\n quoin write . --types FR,domain,entity\n quoin write ../my-service --types fr,DOMAIN --json\n\nNotes:\n - Type lookup is case-insensitive; FR and fr are the same type.\n - Types can be artifacts or objects from the default module set or plugins.\n - Use the returned skeletons and schemas as the authoring contract.\n - Run the returned Quire command after editing spec files.\n", ae = "quoin catalog\n\nInspect the active artifact/object catalog.\n\nThe catalog is assembled from, in order:\n 1. QUOIN_MODULE_PATHS\n 2. modules installed under ~/.ix/filament/modules\n\nThe default module set is installed there automatically on first catalog access,\nand updated by \"quoin plugin install\". The same directory is read by quire-rs.\n\nDefault artifact modules:\n spec-artifacts-iso FR, NFR, StR, US, IT, TC, AC, CON, Spec\n spec-artifacts-app app-level artifacts\n spec-artifacts-process plans, reviews, matrices, ADRs, tasks, findings\n\nDefault object modules:\n spec-objects-business\n spec-objects-architecture\n spec-objects-enterprise\n spec-objects-operational\n spec-objects-security\n\nUsage:\n quoin catalog list\n quoin catalog show <type>\n quoin catalog validate\n\nExamples:\n quoin catalog show FR\n quoin catalog show entity\n quoin catalog validate --json\n", oe = "quoin plugin\n\nInstall and manage user/community spec modules.\n\nPlugins add or override artifact/object modules under ~/.ix/filament/modules.\nUse \"catalog list\" to see the full active catalog, including default modules and\nplugins.\n\nSupported install sources:\n path:<dir> Use a local directory containing manifest.yaml\n github:<owner>/<repo> Clone a GitHub repository (manifest at root)\n github:<owner>/<repo>@<ref> Pin to a tag, branch, or sha\n github:<owner>/<repo>//<subdir> Manifest in a monorepo subdirectory (@<ref> ok)\n\nUsage:\n quoin plugin install <path:...|github:...>\n quoin plugin list\n quoin plugin remove <name>\n quoin plugin ensure-defaults\n\nExamples:\n quoin plugin install path:../spec-objects-custom\n quoin plugin install github:agent-ix/spec-objects-custom\n quoin plugin install github:agent-ix/spec-objects-security//spec_objects_security@v0.1.1\n quoin plugin list\n quoin plugin ensure-defaults\n", se = "quoin update\n\nCheck for and install the latest published quoin.\n\nquoin is distributed on the public npm registry as @agent-ix/quoin. This command\nqueries the registry for the latest version, compares it to the running version,\nand (unless --check) runs npm install -g to upgrade in place.\n\nUsage:\n quoin update [--check] [--registry <url>]\n\nFlags:\n --check Report whether an update is available; do not install.\n --registry <url> Force an npm registry to query/install from. Defaults\n to the public npm registry\n (https://registry.npmjs.org/), where @agent-ix/quoin is\n published. Pass http://npm.ix/ for local dev snapshots.\n\nExamples:\n quoin update\n quoin update --check\n quoin update --registry http://npm.ix/\n", ce = "quoin workflows\n\nStart bundled spec review/planning workflows. quoin creates the workflow run in ~/.ix/flows.\nUse ix-flow to inspect, resume, advance phases, and acknowledge human gates.\n\nAvailable workflow launchers:\n review Run a composite spec review\n matrix Build or update a requirements test matrix\n to-plan Convert accepted requirements into an implementation plan\n\nUsage:\n quoin review|matrix|to-plan [--target <ref>...]\n\nExamples:\n quoin review --target spec/\n quoin matrix --target spec/\n ix-flow status <run-id>\n ix-flow resume <run-id>\n";
309
+ async function le(e) {
310
+ let t = ge(e);
311
311
  if (t.flags.version || t.flags.v || t.command === "version") {
312
312
  console.log(Z());
313
313
  return;
314
314
  }
315
315
  if (!t.command) {
316
- console.log(Y);
316
+ console.log(J);
317
317
  return;
318
318
  }
319
319
  if (t.flags.help || t.flags.h) {
320
- console.log(ce(t));
320
+ console.log(de(t));
321
321
  return;
322
322
  }
323
- let n = Q(t, "config-root") ?? v();
323
+ let n = Q(t, "config-root") ?? g();
324
324
  if (process.env.IX_HOME = n, u({
325
325
  configRoot: n,
326
326
  configNamespace: "ix",
327
327
  projectConfigRoot: `${process.cwd()}/.ix`,
328
328
  projectConfigEnabled: t.flags["no-project-config"] !== !0
329
- }), t.command === "update") return ue(t);
330
- if (t.command === "catalog") return de(t);
331
- if (t.command === "plugin") return fe(t);
332
- if (t.command === "write") return le(t);
333
- if (z().includes(t.command)) return B(t.command, {
329
+ }), t.command === "update") return pe(t);
330
+ if (t.command === "catalog") return me(t);
331
+ if (t.command === "plugin") return he(t);
332
+ if (t.command === "write") return fe(t);
333
+ if (L().includes(t.command)) return R(t.command, {
334
334
  json: t.flags.json === !0,
335
335
  id: Q(t, "id"),
336
336
  target: $(t, "target")
337
337
  });
338
- throw Error(`unknown command ${t.command}\n\n${Y}`);
338
+ throw Error(`unknown command ${t.command}\n\n${J}`);
339
339
  }
340
- function Z() {
340
+ function ue() {
341
341
  let e = o(o(l(import.meta.url))), n = JSON.parse(t(s(e, "package.json"), "utf8"));
342
342
  if (typeof n.version != "string") throw Error("package.json version is missing");
343
343
  return n.version;
344
344
  }
345
- function ce(e) {
346
- return e.command === "update" ? ae : e.command === "write" ? X : e.command === "catalog" ? re : e.command === "plugin" ? ie : z().includes(e.command) ? oe : Y;
345
+ function X(e) {
346
+ return e || ue();
347
+ }
348
+ function Z() {
349
+ return X("0.5.2-dirty");
350
+ }
351
+ function de(e) {
352
+ return e.command === "update" ? se : e.command === "write" ? Y : e.command === "catalog" ? ae : e.command === "plugin" ? oe : L().includes(e.command) ? ce : J;
347
353
  }
348
- function le(e) {
354
+ function fe(e) {
349
355
  let [t] = e.positionals;
350
- if (!t) throw Error(`write requires <repo_dir>\n\n${X}`);
351
- L();
352
- let n = G(x(), t, W($(e, "types")));
353
- console.log(e.flags.json ? JSON.stringify(n, null, 2) : K(n));
356
+ if (!t) throw Error(`write requires <repo_dir>\n\n${Y}`);
357
+ F();
358
+ let n = U(y(), t, H($(e, "types")));
359
+ console.log(e.flags.json ? JSON.stringify(n, null, 2) : W(n));
354
360
  }
355
- async function ue(e) {
361
+ async function pe(e) {
356
362
  await d({
357
363
  packageName: "@agent-ix/quoin",
358
364
  currentVersion: Z(),
359
365
  header: "quoin update",
360
- registry: Q(e, "registry"),
366
+ registry: Q(e, "registry") ?? q,
361
367
  check: e.flags.check === !0
362
368
  });
363
369
  }
364
- function de(e) {
365
- L();
366
- let t = x();
370
+ function me(e) {
371
+ F();
372
+ let t = y();
367
373
  switch (e.subcommand) {
368
374
  case "list":
369
375
  case void 0:
@@ -376,7 +382,7 @@ function de(e) {
376
382
  case "show": {
377
383
  let [n] = e.positionals;
378
384
  if (!n) throw Error("catalog show requires <type>");
379
- let r = S(t, n);
385
+ let r = b(t, n);
380
386
  if (!r) throw Error(`catalog type not found: ${n}`);
381
387
  console.log(e.flags.json ? JSON.stringify(r, null, 2) : `${r.kind} ${r.name} from ${r.moduleName}\n${r.moduleRoot}`);
382
388
  return;
@@ -397,34 +403,34 @@ function de(e) {
397
403
  default: throw Error(`unknown catalog command ${e.subcommand}`);
398
404
  }
399
405
  }
400
- function fe(e) {
406
+ function he(e) {
401
407
  switch (e.subcommand) {
402
408
  case "list":
403
409
  case void 0:
404
- console.log(JSON.stringify({ plugins: M() }, null, 2));
410
+ console.log(JSON.stringify({ plugins: A() }, null, 2));
405
411
  return;
406
412
  case "install": {
407
413
  let [t] = e.positionals;
408
414
  if (!t) throw Error("plugin install requires <source>");
409
- console.log(JSON.stringify(j(t), null, 2));
415
+ console.log(JSON.stringify(k(t), null, 2));
410
416
  return;
411
417
  }
412
418
  case "remove": {
413
419
  let [t] = e.positionals;
414
420
  if (!t) throw Error("plugin remove requires <name>");
415
- N(t), console.log(`removed ${t}`);
421
+ j(t), console.log(`removed ${t}`);
416
422
  return;
417
423
  }
418
424
  case "ensure-defaults":
419
- L(), console.log(JSON.stringify({
425
+ F(), console.log(JSON.stringify({
420
426
  ensured: !0,
421
- plugins: M().map((e) => e.name)
427
+ plugins: A().map((e) => e.name)
422
428
  }, null, 2));
423
429
  return;
424
430
  default: throw Error(`unknown plugin command ${e.subcommand}`);
425
431
  }
426
432
  }
427
- function pe(e) {
433
+ function ge(e) {
428
434
  let t = {}, n = [], r, i;
429
435
  for (let a = 0; a < e.length; a++) {
430
436
  let o = e[a];
@@ -449,4 +455,4 @@ function $(e, t) {
449
455
  return Array.isArray(n) ? n : [];
450
456
  }
451
457
  //#endregion
452
- export { W as a, j as c, N as d, b as f, x as h, K as i, M as l, S as m, Z as n, I as o, y as p, G as r, L as s, se as t, A as u };
458
+ export { W as a, F as c, O as d, j as f, y as g, b as h, U as i, k as l, _ as m, Z as n, H as o, v as p, X as r, P as s, le as t, A as u };
package/dist/cli.d.ts CHANGED
@@ -1,3 +1,4 @@
1
1
  export declare function main(argv: string[]): Promise<void>;
2
+ export declare function resolveVersion(baked: string): string;
2
3
  export declare function packageVersion(): string;
3
4
  //# sourceMappingURL=cli.d.ts.map
package/dist/cli.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA6LA,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCxD;AAED,wBAAgB,cAAc,IAAI,MAAM,CASvC"}
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAkMA,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCxD;AAqBD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}
package/dist/cli.js CHANGED
@@ -1,2 +1,2 @@
1
- import { n as e, t } from "./cli-CQCkDA9J.js";
2
- export { t as main, e as packageVersion };
1
+ import { n as e, r as t, t as n } from "./cli-BtnMrpcK.js";
2
+ export { n as main, e as packageVersion, t as resolveVersion };
package/dist/index.js CHANGED
@@ -1,2 +1,2 @@
1
- import { a as e, c as t, d as n, f as r, h as i, i as a, l as o, m as s, o as c, p as l, r as u, s as d, t as f, u as p } from "./cli-CQCkDA9J.js";
2
- export { u as createAuthoringPack, r as defaultModuleRoots, c as defaultModulesManifest, d as ensureDefaultModules, l as filamentModulesDir, s as findCatalogEntry, a as formatAuthoringPack, t as installPlugin, o as listPlugins, i as loadCatalog, f as main, p as parseSourceArg, e as parseTypeList, n as removePlugin };
1
+ import { a as e, c as t, d as n, f as r, g as i, h as a, i as o, l as s, m as c, o as l, p as u, s as d, t as f, u as p } from "./cli-BtnMrpcK.js";
2
+ export { o as createAuthoringPack, u as defaultModuleRoots, d as defaultModulesManifest, t as ensureDefaultModules, c as filamentModulesDir, a as findCatalogEntry, e as formatAuthoringPack, s as installPlugin, p as listPlugins, i as loadCatalog, f as main, n as parseSourceArg, l as parseTypeList, r as removePlugin };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@agent-ix/quoin",
3
3
  "description": "Spec-driven development for Claude Code — author validated, ISO/IEC/IEEE 29148-aligned specs, then plan and build against them.",
4
- "version": "0.5.0",
4
+ "version": "0.5.2",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "files": [
@@ -42,6 +42,21 @@ file under the matching directory:
42
42
  > If a request asks for functional requirements and you produced only table rows
43
43
  > in `spec.md`, the request is **not done** — create the `FR-XXX.md` files.
44
44
 
45
+ ## Writing good requirements
46
+
47
+ The templates and Quire enforce *shape*; you supply the *judgment*. Author it well
48
+ here so `spec-review` has less to send back. Three principles — full guidance with
49
+ examples in [references/writing-good-requirements.md](references/writing-good-requirements.md):
50
+
51
+ - **Scope: tight beats broad.** Prefer a narrow spec that fully defines its slice over
52
+ a sprawling, vague one. Treat `spec.md` §2.2 Out of Scope as first-class — decide
53
+ your non-goals deliberately; an empty Out-of-Scope is a smell.
54
+ - **User stories: INVEST + no solution-prescribing.** Describe the user need with a
55
+ real "so that …"; let the FRs pick the mechanism.
56
+ - **Acceptance criteria: cover the unhappy paths, be concrete.** Author happy/error/edge
57
+ and negative cases up front, in measurable terms ("returns HTTP 422 within 200ms",
58
+ not "handles errors gracefully").
59
+
45
60
  ## Process
46
61
 
47
62
  Run only the steps the request needs; stop after IT.
@@ -56,9 +71,12 @@ Run only the steps the request needs; stop after IT.
56
71
  - `spec.md` — **REQUIRED when starting a new spec**: the
57
72
  `type: master-requirements` root/index at `spec/spec.md`, authored from
58
73
  `assets/spec-template.md` (or `assets/app-spec-template.md` for an
59
- application). Then → StR → US →
74
+ application); keep scope tight and fill Out of Scope deliberately
75
+ (see [references/writing-good-requirements.md](references/writing-good-requirements.md)).
76
+ Then → StR → US (INVEST, no solution-prescribing — same reference) →
60
77
  **derive FR from US** (see [references/us-to-fr.md](references/us-to-fr.md))
61
- → FR → NFR → IT (see [references/integration-tests.md](references/integration-tests.md)).
78
+ → FR (cover unhappy paths, measurable ACs — same reference)
79
+ → NFR → IT (see [references/integration-tests.md](references/integration-tests.md)).
62
80
  4. Keep traceability in frontmatter `relationships:` (e.g. a US `traces_to` its
63
81
  FRs; an FR/NFR/IT links back to the US/FR it serves).
64
82
  5. Run `quire validate <glob> [glob2 ...]` over the changed spec scope and fix
@@ -80,6 +98,9 @@ each with an Acceptance Criteria table (the `fr.md` skeleton enforces the shape)
80
98
 
81
99
  - Derive FRs from the driving user story — see
82
100
  [references/us-to-fr.md](references/us-to-fr.md).
101
+ - Make the ACs count: cover happy/error/edge and negative cases in concrete,
102
+ measurable terms — see
103
+ [references/writing-good-requirements.md](references/writing-good-requirements.md).
83
104
  - A behavioral FR has no `object:` field. A **domain-typed** FR carries
84
105
  `object: <type>` (e.g. `entity`, `event`, `api_endpoint`, `process`,
85
106
  `configuration`) and uses that type's structural template. Look up the
@@ -0,0 +1,61 @@
1
+ # Writing Good Requirements
2
+
3
+ Load this when authoring StR/US/FR/NFR artifacts. The templates and Quire enforce
4
+ *shape*; this file carries the *judgment* that makes a requirement good, not just
5
+ well-formed. Authoring well here means `spec-review` has less to send back.
6
+
7
+ ## Scope: tight beats broad
8
+
9
+ A narrow spec that fully defines its slice beats a sprawling one full of gaps.
10
+ Resist widening scope to "cover everything" — an expansive, vague spec is worse than
11
+ a tight, sharp one.
12
+
13
+ Treat the `spec.md` §2.2 **Out of Scope** list as first-class. Deliberately decide
14
+ what you are **not** building and write it down — an empty Out-of-Scope section is a
15
+ smell, not a default. Naming non-goals is how you prevent scope creep during
16
+ implementation.
17
+
18
+ > **Bad:** §2.2 left empty; §2.1 In Scope reads "all user-facing features".
19
+ > **Good:** In Scope: "CSV import of contacts". Out of Scope: "XLSX/JSON import,
20
+ > de-duplication, field mapping UI — see future work."
21
+
22
+ ## User stories: INVEST + anti-patterns
23
+
24
+ Aim for **INVEST** stories: **I**ndependent, **N**egotiable, **V**aluable,
25
+ **E**stimable, **S**mall, **T**estable.
26
+
27
+ Catch these anti-patterns while authoring, not in review:
28
+
29
+ - **Vagueness** — "make it faster" says nothing testable. Name the user, the want,
30
+ and a measurable outcome.
31
+ - **Solution-prescribing** — "add a dropdown menu" prescribes a mechanism. A user
32
+ story describes the *need*; the FRs choose the mechanism. If the US already names
33
+ the implementation, you have skipped the problem.
34
+ - **Missing rationale** — every US carries a real "so that …". If you can't state the
35
+ value, question whether the story belongs in the spec.
36
+ - **Internal focus** — "so that the team has less to maintain" benefits the team, not
37
+ the user. Frame the value around the user/stakeholder outcome.
38
+
39
+ > **Bad:** "As a user, I want a dropdown to pick a timezone."
40
+ > **Good:** "As a traveling user, I want event times shown in my current timezone so
41
+ > that I don't miss meetings after I change locations." (The picker, if any, is an FR.)
42
+
43
+ ## Acceptance criteria: cover the unhappy paths, be concrete
44
+
45
+ ACs are authored *here*, with the US/FR — don't defer coverage thinking to
46
+ `spec-matrix`. Front-load it:
47
+
48
+ - **Happy / error / edge from the start.** Walk the same ground the Six Coverage Rules
49
+ (`spec-matrix`) will later check — error paths, constraint boundaries, state
50
+ transitions, edge cases — while the behavior is fresh.
51
+ - **Negative cases.** State what must *not* happen, not just what should: rejects,
52
+ refuses, never persists, leaves state unchanged.
53
+ - **Concrete and measurable.** "Returns HTTP 422 within 200ms", not "handles errors
54
+ gracefully". Avoid subjective language (fast, robust, user-friendly) — if it can't
55
+ be measured, it can't be verified.
56
+ - **Behavior, not implementation.** Assert the observable outcome, not how the code
57
+ achieves it.
58
+
59
+ > **Bad:** "The system handles invalid input gracefully."
60
+ > **Good:** "Given a payload missing `email`, when POST /contacts is called, then the
61
+ > system returns HTTP 422 with error code `MISSING_FIELD` and persists no record."