@guuey/config 0.8.1 → 0.9.0

package/dist/loader.d.ts

@@ -13,7 +13,9 @@ export declare const DEFAULT_FIND_MAX_DEPTH = 8;
 export declare function findGuueyJson(startDir?: string, maxDepth?: number): string | null;
 /**
  * Read + parse `guuey.json` from `path`. Throws if the file is missing,
- * unreadable, malformed JSON, or fails schema validation.
+ * unreadable, malformed JSON, declares a `schema` version this package
+ * cannot honor (`GuueyJsonSchemaError` — `SCHEMA_TOO_NEW` / `SCHEMA_UNSUPPORTED`,
+ * see `assertSupportedGuueyJsonSchema`), or fails schema validation.
  *
  * Does NOT resolve `agent.systemPrompt.file` references. Use
  * {@link loadGuueyJson} for file resolution.

package/dist/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAuBA,OAAO,EAEL,WAAW,EAEZ,MAAM,aAAa,CAAC;AAErB,wEAAwE;AACxE,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,GAAE,MAAsB,EAChC,QAAQ,GAAE,MAA+B,GACxC,MAAM,GAAG,IAAI,CAUf;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAa3D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAIvE;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,GAAG,EAAE,WAAW,CAAC;IACjB;;;;;OAKG;IACH,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAI7D;AAyCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAM1E"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAuBA,OAAO,EAEL,WAAW,EAGZ,MAAM,aAAa,CAAC;AAErB,wEAAwE;AACxE,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,GAAE,MAAsB,EAChC,QAAQ,GAAE,MAA+B,GACxC,MAAM,GAAG,IAAI,CAUf;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAgB3D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAIvE;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,GAAG,EAAE,WAAW,CAAC;IACjB;;;;;OAKG;IACH,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAI7D;AAyCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAM1E"}

package/dist/loader.js

@@ -21,7 +21,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-import { GUUEY_JSON_FILENAME, parseGuueyJson, } from './schema.js';
+import { GUUEY_JSON_FILENAME, assertSupportedGuueyJsonSchema, parseGuueyJson, } from './schema.js';
 /** How many parent directories `findGuueyJson` will walk by default. */
 export const DEFAULT_FIND_MAX_DEPTH = 8;
 /**
@@ -48,7 +48,9 @@ export function findGuueyJson(startDir = process.cwd(), maxDepth = DEFAULT_FIND_
 }
 /**
  * Read + parse `guuey.json` from `path`. Throws if the file is missing,
- * unreadable, malformed JSON, or fails schema validation.
+ * unreadable, malformed JSON, declares a `schema` version this package
+ * cannot honor (`GuueyJsonSchemaError` — `SCHEMA_TOO_NEW` / `SCHEMA_UNSUPPORTED`,
+ * see `assertSupportedGuueyJsonSchema`), or fails schema validation.
  *
  * Does NOT resolve `agent.systemPrompt.file` references. Use
  * {@link loadGuueyJson} for file resolution.
@@ -66,6 +68,9 @@ export function readGuueyJsonFile(path) {
         const msg = err instanceof Error ? err.message : String(err);
         throw new Error(`guuey.json at ${path} is not valid JSON: ${msg}`);
     }
+    // Version gate BEFORE the shape parse: a too-new document must say
+    // "upgrade", not `at "schema": expected "1"` (guuey#248 b2).
+    assertSupportedGuueyJsonSchema(json);
     return parseGuueyJson(json);
 }
 /**

package/dist/schema.d.ts

@@ -41,6 +41,85 @@ import { z } from 'zod';
 import { type GuueyAgent } from './agent.js';
 import { type GuueyApp } from './app.js';
 import { type GuueyGguiSection } from './ggui.js';
+/**
+ * The ONE `guuey.json` `schema` value this package understands — the
+ * schema-version stance (guuey#248 b2):
+ *
+ * - The root `schema` is a decimal integer string (`"1"`, `"2"`, …), bumped
+ *   only on a change that an older reader cannot interpret correctly.
+ * - A document declaring a NEWER schema than this constant is refused
+ *   everywhere: the CLI (`SCHEMA_TOO_NEW` — upgrade `@guuey/cli`) and the
+ *   reconcile / deploy-trigger APIs (`400 SCHEMA_UNSUPPORTED`). Never
+ *   "best-effort parse what we recognize" — the unknown half is precisely
+ *   the half that matters.
+ * - A document declaring an OLDER schema is accepted only when a migration
+ *   to this version exists. Today there is exactly one version and no
+ *   migrations, so the rule collapses to equal-or-refuse; when `"2"` ships,
+ *   the `1 → 2` migration lands in this package and BOTH sides (CLI + API)
+ *   pick it up through {@link classifyGuueyJsonSchema}.
+ *
+ * The CLI and the platform API compare against the SAME constant (both
+ * consume this package), so "the CLI accepted it but the API refused it"
+ * can only ever mean a version skew between the two — which is exactly the
+ * message the API's refusal names.
+ */
+export declare const SUPPORTED_GUUEY_JSON_SCHEMA = "1";
+/**
+ * Where a raw `guuey.json` document's `schema` sits relative to
+ * {@link SUPPORTED_GUUEY_JSON_SCHEMA}:
+ *
+ * - `supported` — equal (or an older version a migration exists for; none
+ *   today).
+ * - `newer` — a later version than this reader knows: refuse + upgrade.
+ * - `older` — an earlier version with NO migration: refuse.
+ * - `invalid` — absent, not a string, or not a decimal integer string; the
+ *   full schema parse reports the precise issue, this verdict only says the
+ *   version-gate cannot even compare.
+ */
+export type GuueyJsonSchemaVerdict = {
+    kind: 'supported';
+    found: string;
+} | {
+    kind: 'newer';
+    found: string;
+} | {
+    kind: 'older';
+    found: string;
+} | {
+    kind: 'invalid';
+    found: string | undefined;
+};
+/**
+ * Classify a raw (JSON-decoded, NOT yet schema-parsed) document's root
+ * `schema` against {@link SUPPORTED_GUUEY_JSON_SCHEMA}. Pure; never throws.
+ * Run it BEFORE `parseGuueyJson` so a too-new document gets the "upgrade
+ * your CLI" face instead of zod's `expected "1"` at the first field.
+ */
+export declare function classifyGuueyJsonSchema(raw: unknown): GuueyJsonSchemaVerdict;
+/**
+ * Thrown by {@link assertSupportedGuueyJsonSchema} — carries the code the
+ * CLI prints and the API maps to its 400 (`SCHEMA_TOO_NEW` = upgrade the
+ * reader; `SCHEMA_UNSUPPORTED` = an older version no migration exists for).
+ * The message already names the found + supported versions and the remedy.
+ */
+export declare class GuueyJsonSchemaError extends Error {
+    readonly code: 'SCHEMA_TOO_NEW' | 'SCHEMA_UNSUPPORTED';
+    readonly found: string;
+    constructor(code: 'SCHEMA_TOO_NEW' | 'SCHEMA_UNSUPPORTED', found: string, message: string);
+}
+/**
+ * Refuse a document whose `schema` this reader cannot honor. `invalid`
+ * verdicts pass through untouched — the schema parse that follows reports
+ * the precise issue (`at "schema": expected "1"`), which is the right face
+ * for a typo; this gate exists for the version SKEW cases only.
+ *
+ * Runs inside `readGuueyJsonFile` / `loadGuueyJson` (every CLI read of a
+ * checked-in file — `deploy`, `dev`, `agent apply`, …) and in the platform's
+ * reconcile + deploy-trigger handlers, so both ends of the wire refuse the
+ * same documents for the same reason. The message names the remedy for the
+ * only reader outside the platform: the CLI.
+ */
+export declare function assertSupportedGuueyJsonSchema(raw: unknown): void;
 /**
  * Top-level guuey.json v1 schema.
  *

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAEjE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAmDtB,CAAC;AAEH,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAG3D,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAExD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,WAAW,CAAC,SAAS,CAAC,CAE1C"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEnD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,sBAAsB,CAY5E;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aAE3B,IAAI,EAAE,gBAAgB,GAAG,oBAAoB;aAC7C,KAAK,EAAE,MAAM;gBADb,IAAI,EAAE,gBAAgB,GAAG,oBAAoB,EAC7C,KAAK,EAAE,MAAM,EAC7B,OAAO,EAAE,MAAM;CAKlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAkBjE;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAmDtB,CAAC;AAEH,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAG3D,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAExD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,WAAW,CAAC,SAAS,CAAC,CAE1C"}

package/dist/schema.js

@@ -41,6 +41,87 @@ import { z } from 'zod';
 import { AgentSectionV1 } from './agent.js';
 import { AppSectionV1 } from './app.js';
 import { GguiSectionV1 } from './ggui.js';
+/**
+ * The ONE `guuey.json` `schema` value this package understands — the
+ * schema-version stance (guuey#248 b2):
+ *
+ * - The root `schema` is a decimal integer string (`"1"`, `"2"`, …), bumped
+ *   only on a change that an older reader cannot interpret correctly.
+ * - A document declaring a NEWER schema than this constant is refused
+ *   everywhere: the CLI (`SCHEMA_TOO_NEW` — upgrade `@guuey/cli`) and the
+ *   reconcile / deploy-trigger APIs (`400 SCHEMA_UNSUPPORTED`). Never
+ *   "best-effort parse what we recognize" — the unknown half is precisely
+ *   the half that matters.
+ * - A document declaring an OLDER schema is accepted only when a migration
+ *   to this version exists. Today there is exactly one version and no
+ *   migrations, so the rule collapses to equal-or-refuse; when `"2"` ships,
+ *   the `1 → 2` migration lands in this package and BOTH sides (CLI + API)
+ *   pick it up through {@link classifyGuueyJsonSchema}.
+ *
+ * The CLI and the platform API compare against the SAME constant (both
+ * consume this package), so "the CLI accepted it but the API refused it"
+ * can only ever mean a version skew between the two — which is exactly the
+ * message the API's refusal names.
+ */
+export const SUPPORTED_GUUEY_JSON_SCHEMA = '1';
+/**
+ * Classify a raw (JSON-decoded, NOT yet schema-parsed) document's root
+ * `schema` against {@link SUPPORTED_GUUEY_JSON_SCHEMA}. Pure; never throws.
+ * Run it BEFORE `parseGuueyJson` so a too-new document gets the "upgrade
+ * your CLI" face instead of zod's `expected "1"` at the first field.
+ */
+export function classifyGuueyJsonSchema(raw) {
+    const found = raw !== null && typeof raw === 'object' && 'schema' in raw
+        ? raw.schema
+        : undefined;
+    if (typeof found !== 'string' || !/^[1-9][0-9]*$/.test(found)) {
+        return { kind: 'invalid', found: typeof found === 'string' ? found : undefined };
+    }
+    const have = Number.parseInt(SUPPORTED_GUUEY_JSON_SCHEMA, 10);
+    const got = Number.parseInt(found, 10);
+    if (got === have)
+        return { kind: 'supported', found };
+    return got > have ? { kind: 'newer', found } : { kind: 'older', found };
+}
+/**
+ * Thrown by {@link assertSupportedGuueyJsonSchema} — carries the code the
+ * CLI prints and the API maps to its 400 (`SCHEMA_TOO_NEW` = upgrade the
+ * reader; `SCHEMA_UNSUPPORTED` = an older version no migration exists for).
+ * The message already names the found + supported versions and the remedy.
+ */
+export class GuueyJsonSchemaError extends Error {
+    code;
+    found;
+    constructor(code, found, message) {
+        super(message);
+        this.code = code;
+        this.found = found;
+        this.name = 'GuueyJsonSchemaError';
+    }
+}
+/**
+ * Refuse a document whose `schema` this reader cannot honor. `invalid`
+ * verdicts pass through untouched — the schema parse that follows reports
+ * the precise issue (`at "schema": expected "1"`), which is the right face
+ * for a typo; this gate exists for the version SKEW cases only.
+ *
+ * Runs inside `readGuueyJsonFile` / `loadGuueyJson` (every CLI read of a
+ * checked-in file — `deploy`, `dev`, `agent apply`, …) and in the platform's
+ * reconcile + deploy-trigger handlers, so both ends of the wire refuse the
+ * same documents for the same reason. The message names the remedy for the
+ * only reader outside the platform: the CLI.
+ */
+export function assertSupportedGuueyJsonSchema(raw) {
+    const verdict = classifyGuueyJsonSchema(raw);
+    if (verdict.kind === 'newer') {
+        throw new GuueyJsonSchemaError('SCHEMA_TOO_NEW', verdict.found, `guuey.json declares schema "${verdict.found}", but this reader understands schema "${SUPPORTED_GUUEY_JSON_SCHEMA}" only. ` +
+            'Upgrade the tool reading it — for the CLI: npm i -g @guuey/cli@latest — and re-run.');
+    }
+    if (verdict.kind === 'older') {
+        throw new GuueyJsonSchemaError('SCHEMA_UNSUPPORTED', verdict.found, `guuey.json declares schema "${verdict.found}", but no migration to schema "${SUPPORTED_GUUEY_JSON_SCHEMA}" exists — ` +
+            `set "schema": "${SUPPORTED_GUUEY_JSON_SCHEMA}" and update the document to the current shape.`);
+    }
+}
 /**
  * Top-level guuey.json v1 schema.
  *
@@ -54,7 +135,7 @@ import { GguiSectionV1 } from './ggui.js';
  * Re-exports the sub-section types for consumer convenience.
  */
 export const GuueyJsonV1 = z.strictObject({
-    schema: z.literal('1'),
+    schema: z.literal(SUPPORTED_GUUEY_JSON_SCHEMA),
     /** Stable agent identifier minted by the control plane on first `guuey create`. */
     appId: z.string().min(1).max(128).optional(),
     /** Workspace the project lives under. Optional — personal apps + freshly-linked apps. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/config",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Open-source schemas + loaders for the three guuey config files: agent.json (declarative agent definition), guuey.json (hosted-deploy overlay), and the helper types around them. Consumed by @guuey/cli, the guuey backend, and devs writing their own agent or MCP server.",
   "license": "MIT",
   "type": "module",