@cristochang/spec-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenCode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @cristochang/spec-core
+
+Spec data structures and validation library for OpenCode.
+
+## Installation
+
+```bash
+npm install @cristochang/spec-core
+```
+
+## Overview
+
+This package provides the core data structures and validation logic for OpenCode's Spec workflow. It includes:
+
+- **Spec Schema** - Zod schemas for Spec data structures
+- **Validator** - Business-level validation logic
+- **Spec API** - Utility functions for creating and manipulating specs
+
+## Usage
+
+### Creating a Spec
+
+```typescript
+import { Spec } from '@cristochang/spec-core'
+
+const spec = Spec.create({
+  objective: "Add user authentication feature",
+  scope: {
+    inclusions: ["login page", "auth service"],
+    exclusions: ["social login"]
+  },
+  successCriteria: ["Users can log in with email/password", "Session management works"]
+})
+
+console.log(spec.id)        // ULID
+console.log(spec.status)     // "pending"
+console.log(spec.created)    // ISO 8601 timestamp
+```
+
+### Validating a Spec
+
+```typescript
+import { Spec } from '@cristochang/spec-core'
+
+const result = Spec.validate(spec)
+
+if (!result.valid) {
+  console.log("Missing fields:", result.missing)
+  console.log("Errors:", result.errors)
+}
+```
+
+### Status Transitions
+
+```typescript
+import { Spec } from '@cristochang/spec-core'
+
+// Pending -> Approved
+const approved = Spec.approve(spec)
+
+// Approved -> Implemented
+const implemented = Spec.markImplemented(approved, "All tests passing")
+
+// Any status -> Cancelled
+const cancelled = Spec.cancel(spec)
+```
+
+### Checking Execution Readiness
+
+```typescript
+import { Spec } from '@cristochang/spec-core'
+
+if (Spec.canExecute(spec)) {
+  console.log("Spec is ready for execution")
+}
+```
+
+## Data Structure
+
+```typescript
+interface SpecInfo {
+  // Meta (required)
+  id: string                      // ULID
+  created: string                 // ISO 8601 datetime
+  status: "pending" | "approved" | "implemented" | "cancelled"
+
+  // Core (required)
+  objective: string               // Clear one-sentence objective
+  scope: {
+    inclusions: string[]          // Items in scope
+    exclusions: string[]          // Items out of scope
+  }
+  successCriteria: string[]       // Verifiable success criteria
+
+  // Optional
+  constraints?: string[]          // Technical/architectural constraints
+  implementationNotes?: string    // Non-binding guidance
+
+  // Auto-filled
+  changes?: string[]              // Files modified
+  verification?: string           // Verification result
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import type { SpecInfo, SpecStatus } from "./schema";
+import { Validator } from "./validator";
+export { SpecInfo, SpecStatus } from "./schema";
+export { Validator } from "./validator";
+/**
+ * Spec namespace containing all spec-related utilities
+ */
+export declare namespace Spec {
+    /**
+     * Create a new spec with default values
+     */
+    function create(input: Partial<SpecInfo> & Pick<SpecInfo, "objective" | "scope" | "successCriteria">): SpecInfo;
+    /**
+     * Validate a spec (convenience alias)
+     */
+    function validate(spec: SpecInfo): Validator.ValidationResult;
+    /**
+     * Check if a spec can be executed (convenience alias)
+     */
+    function canExecute(spec: SpecInfo): boolean;
+    /**
+     * Update spec status
+     */
+    function updateStatus(spec: SpecInfo, status: SpecStatus): SpecInfo;
+    /**
+     * Approve a spec
+     */
+    function approve(spec: SpecInfo): SpecInfo;
+    /**
+     * Mark a spec as implemented
+     */
+    function markImplemented(spec: SpecInfo, verification?: string): SpecInfo;
+    /**
+     * Cancel a spec
+     */
+    function cancel(spec: SpecInfo): SpecInfo;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEvC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEvC;;GAEG;AACH,yBAAiB,IAAI,CAAC;IACpB;;OAEG;IACH,SAAgB,MAAM,CACpB,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,GAAG,iBAAiB,CAAC,GACnF,QAAQ,CAaV;IAED;;OAEG;IACH,SAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,8BAEtC;IAED;;OAEG;IACH,SAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAElD;IAED;;OAEG;IACH,SAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAG,QAAQ,CAEzE;IAED;;OAEG;IACH,SAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAEhD;IAED;;OAEG;IACH,SAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,CAM/E;IAED;;OAEG;IACH,SAAgB,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAE/C;CACF"}

package/dist/index.js

@@ -0,0 +1,101 @@
+// src/index.ts
+import { ulid } from "ulid";
+
+// src/validator.ts
+var Validator;
+((Validator2) => {
+  function validate(spec) {
+    const missing = [];
+    const errors = [];
+    if (!spec.objective?.trim()) missing.push("objective");
+    if (!spec.successCriteria?.length) missing.push("successCriteria");
+    return {
+      valid: missing.length === 0 && errors.length === 0,
+      missing,
+      errors
+    };
+  }
+  Validator2.validate = validate;
+  function canExecute(spec) {
+    return spec.status === "approved" && validate(spec).valid;
+  }
+  Validator2.canExecute = canExecute;
+})(Validator || (Validator = {}));
+
+// src/schema.ts
+import z from "zod";
+var SpecStatusSchema = z.enum(["pending", "approved", "implemented", "cancelled"]);
+var SpecInfo = z.object({
+  // Meta (required)
+  id: z.string().describe("Unique identifier for the spec (ULID)"),
+  created: z.string().datetime().describe("ISO 8601 timestamp of creation (Zod validated)"),
+  status: SpecStatusSchema.describe("Current status of the spec"),
+  // Core (required)
+  objective: z.string().describe("Clear, one-sentence objective"),
+  scope: z.object({
+    inclusions: z.array(z.string()).min(1).describe("Items to include in scope (at least one)"),
+    exclusions: z.array(z.string()).min(0).describe("Items explicitly excluded from scope")
+  }).describe("Scope boundaries"),
+  successCriteria: z.array(z.string()).describe("Verifiable success criteria"),
+  // Optional
+  constraints: z.array(z.string()).optional().describe("Technical or architectural constraints"),
+  implementationNotes: z.string().optional().describe("Non-binding implementation guidance for AI; not a requirement"),
+  // Auto-filled (optional)
+  changes: z.array(z.string().min(1)).optional().describe("List of files modified (auto-filled, non-empty strings)"),
+  verification: z.string().optional().describe("Verification result (auto-filled)")
+}).meta({
+  ref: "Spec"
+});
+
+// src/index.ts
+var Spec;
+((Spec2) => {
+  function create(input) {
+    return {
+      id: input.id ?? ulid(),
+      created: input.created ?? (/* @__PURE__ */ new Date()).toISOString(),
+      status: input.status ?? "pending",
+      objective: input.objective,
+      scope: input.scope,
+      successCriteria: input.successCriteria,
+      constraints: input.constraints,
+      implementationNotes: input.implementationNotes,
+      changes: input.changes,
+      verification: input.verification
+    };
+  }
+  Spec2.create = create;
+  function validate(spec) {
+    return Validator.validate(spec);
+  }
+  Spec2.validate = validate;
+  function canExecute(spec) {
+    return Validator.canExecute(spec);
+  }
+  Spec2.canExecute = canExecute;
+  function updateStatus(spec, status) {
+    return { ...spec, status };
+  }
+  Spec2.updateStatus = updateStatus;
+  function approve(spec) {
+    return updateStatus(spec, "approved");
+  }
+  Spec2.approve = approve;
+  function markImplemented(spec, verification) {
+    return {
+      ...spec,
+      status: "implemented",
+      verification: verification ?? spec.verification
+    };
+  }
+  Spec2.markImplemented = markImplemented;
+  function cancel(spec) {
+    return updateStatus(spec, "cancelled");
+  }
+  Spec2.cancel = cancel;
+})(Spec || (Spec = {}));
+export {
+  Spec,
+  SpecInfo,
+  Validator
+};

package/dist/schema.d.ts

@@ -0,0 +1,12 @@
+import z from "zod";
+/**
+ * Spec status values
+ */
+export declare const SpecStatusSchema: any;
+export type SpecStatus = z.infer<typeof SpecStatusSchema>;
+/**
+ * Main Spec data structure
+ */
+export declare const SpecInfo: any;
+export type SpecInfo = z.infer<typeof SpecInfo>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,KAAK,CAAA;AAEnB;;GAEG;AACH,eAAO,MAAM,gBAAgB,KAA8D,CAAA;AAC3F,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEzD;;GAEG;AACH,eAAO,MAAM,QAAQ,KAoCjB,CAAA;AAEJ,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAA"}

package/dist/schema.js

@@ -0,0 +1,42 @@
+import z from "zod";
+/**
+ * Spec status values
+ */
+export const SpecStatusSchema = z.enum(["pending", "approved", "implemented", "cancelled"]);
+/**
+ * Main Spec data structure
+ */
+export const SpecInfo = z
+    .object({
+    // Meta (required)
+    id: z.string().describe("Unique identifier for the spec (ULID)"),
+    created: z
+        .string()
+        .datetime()
+        .describe("ISO 8601 timestamp of creation (Zod validated)"),
+    status: SpecStatusSchema.describe("Current status of the spec"),
+    // Core (required)
+    objective: z.string().describe("Clear, one-sentence objective"),
+    scope: z
+        .object({
+        inclusions: z.array(z.string()).min(1).describe("Items to include in scope (at least one)"),
+        exclusions: z.array(z.string()).min(0).describe("Items explicitly excluded from scope"),
+    })
+        .describe("Scope boundaries"),
+    successCriteria: z.array(z.string()).describe("Verifiable success criteria"),
+    // Optional
+    constraints: z.array(z.string()).optional().describe("Technical or architectural constraints"),
+    implementationNotes: z
+        .string()
+        .optional()
+        .describe("Non-binding implementation guidance for AI; not a requirement"),
+    // Auto-filled (optional)
+    changes: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("List of files modified (auto-filled, non-empty strings)"),
+    verification: z.string().optional().describe("Verification result (auto-filled)"),
+})
+    .meta({
+    ref: "Spec",
+});

package/dist/validator.d.ts

@@ -0,0 +1,21 @@
+import type { SpecInfo } from "./schema";
+export declare namespace Validator {
+    interface ValidationResult {
+        valid: boolean;
+        missing: string[];
+        errors: string[];
+    }
+    /**
+     * Validate Spec's business-level completeness
+     *
+     * Note: Basic data format validation is done by Zod schema during parse
+     * This only handles business logic related validation
+     */
+    function validate(spec: SpecInfo): ValidationResult;
+    /**
+     * Check if Spec can be executed
+     * Requires: status is "approved" and business-level validation passes
+     */
+    function canExecute(spec: SpecInfo): boolean;
+}
+//# sourceMappingURL=validator.d.ts.map

package/dist/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAExC,yBAAiB,SAAS,CAAC;IACzB,UAAiB,gBAAgB;QAC/B,KAAK,EAAE,OAAO,CAAA;QACd,OAAO,EAAE,MAAM,EAAE,CAAA;QACjB,MAAM,EAAE,MAAM,EAAE,CAAA;KACjB;IAED;;;;;OAKG;IACH,SAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,gBAAgB,CAezD;IAED;;;OAGG;IACH,SAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAElD;CACF"}

package/dist/validator.js

@@ -0,0 +1,33 @@
+export var Validator;
+(function (Validator) {
+    /**
+     * Validate Spec's business-level completeness
+     *
+     * Note: Basic data format validation is done by Zod schema during parse
+     * This only handles business logic related validation
+     */
+    function validate(spec) {
+        const missing = [];
+        const errors = [];
+        // Business-level checks: non-empty validation (Zod already ensures arrays exist, here we check content)
+        if (!spec.objective?.trim())
+            missing.push("objective");
+        if (!spec.successCriteria?.length)
+            missing.push("successCriteria");
+        // Zod already ensures status is a valid value, no need to re-validate
+        return {
+            valid: missing.length === 0 && errors.length === 0,
+            missing,
+            errors,
+        };
+    }
+    Validator.validate = validate;
+    /**
+     * Check if Spec can be executed
+     * Requires: status is "approved" and business-level validation passes
+     */
+    function canExecute(spec) {
+        return spec.status === "approved" && validate(spec).valid;
+    }
+    Validator.canExecute = canExecute;
+})(Validator || (Validator = {}));

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@cristochang/spec-core",
+  "version": "0.1.0",
+  "description": "Spec data structures and validation for OpenCode",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.js"
+    },
+    "./validator": {
+      "types": "./dist/validator.d.ts",
+      "import": "./dist/validator.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun run build:js && bun run build:dts",
+    "build:js": "bunx esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --external:zod --external:ulid",
+    "build:dts": "bunx tsc --emitDeclarationOnly",
+    "build:npm": "npx esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --external:zod --external:ulid && npx typescript --emitDeclarationOnly",
+    "test": "bun test"
+  },
+  "keywords": [
+    "opencode",
+    "spec",
+    "validation",
+    "schema",
+    "workflow"
+  ],
+  "author": "OpenCode",
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.0.0",
+    "ulid": "^2.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.13.9",
+    "esbuild": "0.27.2",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}