@hasna/contracts 0.1.0 → 0.2.0

package/dist/schemas.js

@@ -3989,7 +3989,7 @@ var coerce = {
 var NEVER = INVALID;
 // src/schemas.ts
 var CONTRACTS_PACKAGE_NAME = "@hasna/contracts";
-var CONTRACTS_PACKAGE_VERSION = "0.1.0";
+var CONTRACTS_PACKAGE_VERSION = "0.2.0";
 var SCHEMA_IDS = {
   actorRef: "hasna.actor_ref.v1",
   resourceRef: "hasna.resource_ref.v1",
@@ -4001,7 +4001,9 @@ var SCHEMA_IDS = {
   contextPack: "hasna.context_pack.v1",
   agentTrajectory: "hasna.agent_trajectory.v1",
   validationPlan: "hasna.validation_plan.v1",
-  proofBundle: "hasna.proof_bundle.v1"
+  proofBundle: "hasna.proof_bundle.v1",
+  scaffoldManifest: "hasna.scaffold_manifest.v1",
+  scaffoldInstallRecord: "hasna.scaffold_install_record.v1"
 };
 var SchemaIdSchema = exports_external.string().regex(/^hasna\.[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*\.v[0-9]+$/);
 var TimestampSchema = exports_external.string().datetime();
@@ -4305,6 +4307,144 @@ var ValidationPlanSchema = contractBaseSchema(SCHEMA_IDS.validationPlan).extend(
   verifier: ActorPointerSchema.optional(),
   requiredEvidenceKinds: exports_external.array(EvidenceKindSchema).default([])
 }).strict();
+var ScaffoldTypeSchema = exports_external.enum([
+  "open_source",
+  "internal_app",
+  "platform",
+  "app",
+  "agent",
+  "content",
+  "overlay",
+  "other"
+]);
+var ScaffoldStatusSchema = exports_external.enum(["draft", "active", "deprecated", "archived"]);
+var ScaffoldCapabilitySchema = exports_external.enum([
+  "cli",
+  "mcp",
+  "library",
+  "sdk",
+  "rest_api",
+  "dashboard",
+  "database",
+  "auth",
+  "billing",
+  "worker",
+  "daemon",
+  "native",
+  "browser_extension",
+  "ai_provider",
+  "media_pipeline",
+  "data_pipeline",
+  "tests",
+  "ci",
+  "deployment",
+  "docs",
+  "other"
+]);
+var ScaffoldEnvVarSchema = exports_external.object({
+  key: exports_external.string().regex(/^[A-Z][A-Z0-9_]*$/),
+  description: exports_external.string().min(1),
+  required: exports_external.boolean().default(false),
+  secret: exports_external.boolean().default(false),
+  group: exports_external.string().min(1).optional(),
+  default: exports_external.string().optional()
+}).strict().superRefine((value, ctx) => {
+  if (value.secret && value.default !== undefined) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "Secret scaffold env vars cannot include defaults",
+      path: ["default"]
+    });
+  }
+});
+var ScaffoldScriptSchema = exports_external.object({
+  name: exports_external.string().min(1),
+  command: exports_external.string().min(1),
+  description: exports_external.string().min(1).optional(),
+  required: exports_external.boolean().default(false)
+}).strict();
+var ScaffoldOutputShapeSchema = exports_external.object({
+  packageManager: exports_external.enum(["bun", "npm", "pnpm", "yarn", "cargo", "pip", "other"]).optional(),
+  languages: exports_external.array(exports_external.string().min(1)).default([]),
+  requiredFiles: exports_external.array(exports_external.string().min(1)).default([]),
+  requiredDirectories: exports_external.array(exports_external.string().min(1)).default([]),
+  optionalDirectories: exports_external.array(exports_external.string().min(1)).default([])
+}).strict();
+var ScaffoldManifestSchema = contractBaseSchema(SCHEMA_IDS.scaffoldManifest).extend({
+  name: exports_external.string().min(1),
+  version: exports_external.string().min(1),
+  summary: exports_external.string().min(1),
+  type: ScaffoldTypeSchema,
+  status: ScaffoldStatusSchema.default("draft"),
+  capabilities: exports_external.array(ScaffoldCapabilitySchema).default([]),
+  techStack: exports_external.array(exports_external.string().min(1)).default([]),
+  tags: TagsSchema,
+  source: ResourcePointerSchema.optional(),
+  output: ScaffoldOutputShapeSchema,
+  env: exports_external.array(ScaffoldEnvVarSchema).default([]),
+  scripts: exports_external.array(ScaffoldScriptSchema).default([]),
+  validationChecks: exports_external.array(ValidationCheckSchema).default([]),
+  evidenceRefs: exports_external.array(EvidencePointerSchema).default([])
+}).strict().superRefine((value, ctx) => {
+  if (value.source?.uri?.startsWith("file://")) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "Public scaffold manifest source refs cannot use local file:// URIs",
+      path: ["source", "uri"]
+    });
+  }
+  if (value.status === "active" && value.validationChecks.length === 0) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "Active scaffold manifests require validation checks",
+      path: ["validationChecks"]
+    });
+  }
+  if (value.status === "active" && value.output.requiredFiles.length === 0 && value.output.requiredDirectories.length === 0) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "Active scaffold manifests require at least one required file or directory",
+      path: ["output"]
+    });
+  }
+});
+var ScaffoldInstallStatusSchema = exports_external.enum(["installed", "failed", "cancelled", "partial", "unknown"]);
+var ScaffoldInstallRecordSchema = contractBaseSchema(SCHEMA_IDS.scaffoldInstallRecord).extend({
+  scaffoldId: exports_external.string().min(1),
+  scaffoldVersion: exports_external.string().min(1).optional(),
+  manifestRef: ResourcePointerSchema.optional(),
+  target: ResourcePointerSchema,
+  status: ScaffoldInstallStatusSchema,
+  installedAt: TimestampSchema.optional(),
+  installer: ActorPointerSchema.optional(),
+  packageManager: exports_external.enum(["bun", "npm", "pnpm", "yarn", "cargo", "pip", "other"]).optional(),
+  options: MetadataSchema.optional(),
+  generatedFiles: exports_external.array(ResourcePointerSchema).default([]),
+  evidenceRefs: exports_external.array(EvidencePointerSchema).default([]),
+  proofBundleRefs: exports_external.array(ResourcePointerSchema).default([])
+}).strict().superRefine((value, ctx) => {
+  if (value.status === "installed" && !value.installedAt) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "Installed scaffold records require installedAt",
+      path: ["installedAt"]
+    });
+  }
+  if (value.status === "installed" && value.generatedFiles.length === 0 && value.evidenceRefs.length === 0 && value.proofBundleRefs.length === 0) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "Installed scaffold records require generated files, evidence, or proof bundle refs",
+      path: ["generatedFiles"]
+    });
+  }
+  if ((value.status === "failed" || value.status === "partial") && value.evidenceRefs.length === 0 && value.proofBundleRefs.length === 0) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "Failed or partial scaffold records require evidence or proof bundle refs",
+      path: ["evidenceRefs"]
+    });
+  }
+});
 var ProofCheckResultSchema = exports_external.object({
   checkId: exports_external.string().min(1),
   status: ContractStatusSchema,
@@ -4451,7 +4591,9 @@ var ContractSchemaRegistry = {
   [SCHEMA_IDS.contextPack]: ContextPackSchema,
   [SCHEMA_IDS.agentTrajectory]: AgentTrajectorySchema,
   [SCHEMA_IDS.validationPlan]: ValidationPlanSchema,
-  [SCHEMA_IDS.proofBundle]: ProofBundleSchema
+  [SCHEMA_IDS.proofBundle]: ProofBundleSchema,
+  [SCHEMA_IDS.scaffoldManifest]: ScaffoldManifestSchema,
+  [SCHEMA_IDS.scaffoldInstallRecord]: ScaffoldInstallRecordSchema
 };
 export {
   contractBaseSchema,
@@ -4464,6 +4606,15 @@ export {
   TagsSchema,
   Sha256DigestSchema,
   SchemaIdSchema,
+  ScaffoldTypeSchema,
+  ScaffoldStatusSchema,
+  ScaffoldScriptSchema,
+  ScaffoldOutputShapeSchema,
+  ScaffoldManifestSchema,
+  ScaffoldInstallStatusSchema,
+  ScaffoldInstallRecordSchema,
+  ScaffoldEnvVarSchema,
+  ScaffoldCapabilitySchema,
   SCHEMA_IDS,
   ResourceRefSchema,
   ResourcePointerSchema,

package/dist/validators.js

@@ -3989,7 +3989,7 @@ var coerce = {
 var NEVER = INVALID;
 // src/schemas.ts
 var CONTRACTS_PACKAGE_NAME = "@hasna/contracts";
-var CONTRACTS_PACKAGE_VERSION = "0.1.0";
+var CONTRACTS_PACKAGE_VERSION = "0.2.0";
 var SCHEMA_IDS = {
   actorRef: "hasna.actor_ref.v1",
   resourceRef: "hasna.resource_ref.v1",
@@ -4001,7 +4001,9 @@ var SCHEMA_IDS = {
   contextPack: "hasna.context_pack.v1",
   agentTrajectory: "hasna.agent_trajectory.v1",
   validationPlan: "hasna.validation_plan.v1",
-  proofBundle: "hasna.proof_bundle.v1"
+  proofBundle: "hasna.proof_bundle.v1",
+  scaffoldManifest: "hasna.scaffold_manifest.v1",
+  scaffoldInstallRecord: "hasna.scaffold_install_record.v1"
 };
 var SchemaIdSchema = exports_external.string().regex(/^hasna\.[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*\.v[0-9]+$/);
 var TimestampSchema = exports_external.string().datetime();
@@ -4305,6 +4307,144 @@ var ValidationPlanSchema = contractBaseSchema(SCHEMA_IDS.validationPlan).extend(
   verifier: ActorPointerSchema.optional(),
   requiredEvidenceKinds: exports_external.array(EvidenceKindSchema).default([])
 }).strict();
+var ScaffoldTypeSchema = exports_external.enum([
+  "open_source",
+  "internal_app",
+  "platform",
+  "app",
+  "agent",
+  "content",
+  "overlay",
+  "other"
+]);
+var ScaffoldStatusSchema = exports_external.enum(["draft", "active", "deprecated", "archived"]);
+var ScaffoldCapabilitySchema = exports_external.enum([
+  "cli",
+  "mcp",
+  "library",
+  "sdk",
+  "rest_api",
+  "dashboard",
+  "database",
+  "auth",
+  "billing",
+  "worker",
+  "daemon",
+  "native",
+  "browser_extension",
+  "ai_provider",
+  "media_pipeline",
+  "data_pipeline",
+  "tests",
+  "ci",
+  "deployment",
+  "docs",
+  "other"
+]);
+var ScaffoldEnvVarSchema = exports_external.object({
+  key: exports_external.string().regex(/^[A-Z][A-Z0-9_]*$/),
+  description: exports_external.string().min(1),
+  required: exports_external.boolean().default(false),
+  secret: exports_external.boolean().default(false),
+  group: exports_external.string().min(1).optional(),
+  default: exports_external.string().optional()
+}).strict().superRefine((value, ctx) => {
+  if (value.secret && value.default !== undefined) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "Secret scaffold env vars cannot include defaults",
+      path: ["default"]
+    });
+  }
+});
+var ScaffoldScriptSchema = exports_external.object({
+  name: exports_external.string().min(1),
+  command: exports_external.string().min(1),
+  description: exports_external.string().min(1).optional(),
+  required: exports_external.boolean().default(false)
+}).strict();
+var ScaffoldOutputShapeSchema = exports_external.object({
+  packageManager: exports_external.enum(["bun", "npm", "pnpm", "yarn", "cargo", "pip", "other"]).optional(),
+  languages: exports_external.array(exports_external.string().min(1)).default([]),
+  requiredFiles: exports_external.array(exports_external.string().min(1)).default([]),
+  requiredDirectories: exports_external.array(exports_external.string().min(1)).default([]),
+  optionalDirectories: exports_external.array(exports_external.string().min(1)).default([])
+}).strict();
+var ScaffoldManifestSchema = contractBaseSchema(SCHEMA_IDS.scaffoldManifest).extend({
+  name: exports_external.string().min(1),
+  version: exports_external.string().min(1),
+  summary: exports_external.string().min(1),
+  type: ScaffoldTypeSchema,
+  status: ScaffoldStatusSchema.default("draft"),
+  capabilities: exports_external.array(ScaffoldCapabilitySchema).default([]),
+  techStack: exports_external.array(exports_external.string().min(1)).default([]),
+  tags: TagsSchema,
+  source: ResourcePointerSchema.optional(),
+  output: ScaffoldOutputShapeSchema,
+  env: exports_external.array(ScaffoldEnvVarSchema).default([]),
+  scripts: exports_external.array(ScaffoldScriptSchema).default([]),
+  validationChecks: exports_external.array(ValidationCheckSchema).default([]),
+  evidenceRefs: exports_external.array(EvidencePointerSchema).default([])
+}).strict().superRefine((value, ctx) => {
+  if (value.source?.uri?.startsWith("file://")) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "Public scaffold manifest source refs cannot use local file:// URIs",
+      path: ["source", "uri"]
+    });
+  }
+  if (value.status === "active" && value.validationChecks.length === 0) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "Active scaffold manifests require validation checks",
+      path: ["validationChecks"]
+    });
+  }
+  if (value.status === "active" && value.output.requiredFiles.length === 0 && value.output.requiredDirectories.length === 0) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "Active scaffold manifests require at least one required file or directory",
+      path: ["output"]
+    });
+  }
+});
+var ScaffoldInstallStatusSchema = exports_external.enum(["installed", "failed", "cancelled", "partial", "unknown"]);
+var ScaffoldInstallRecordSchema = contractBaseSchema(SCHEMA_IDS.scaffoldInstallRecord).extend({
+  scaffoldId: exports_external.string().min(1),
+  scaffoldVersion: exports_external.string().min(1).optional(),
+  manifestRef: ResourcePointerSchema.optional(),
+  target: ResourcePointerSchema,
+  status: ScaffoldInstallStatusSchema,
+  installedAt: TimestampSchema.optional(),
+  installer: ActorPointerSchema.optional(),
+  packageManager: exports_external.enum(["bun", "npm", "pnpm", "yarn", "cargo", "pip", "other"]).optional(),
+  options: MetadataSchema.optional(),
+  generatedFiles: exports_external.array(ResourcePointerSchema).default([]),
+  evidenceRefs: exports_external.array(EvidencePointerSchema).default([]),
+  proofBundleRefs: exports_external.array(ResourcePointerSchema).default([])
+}).strict().superRefine((value, ctx) => {
+  if (value.status === "installed" && !value.installedAt) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "Installed scaffold records require installedAt",
+      path: ["installedAt"]
+    });
+  }
+  if (value.status === "installed" && value.generatedFiles.length === 0 && value.evidenceRefs.length === 0 && value.proofBundleRefs.length === 0) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "Installed scaffold records require generated files, evidence, or proof bundle refs",
+      path: ["generatedFiles"]
+    });
+  }
+  if ((value.status === "failed" || value.status === "partial") && value.evidenceRefs.length === 0 && value.proofBundleRefs.length === 0) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "Failed or partial scaffold records require evidence or proof bundle refs",
+      path: ["evidenceRefs"]
+    });
+  }
+});
 var ProofCheckResultSchema = exports_external.object({
   checkId: exports_external.string().min(1),
   status: ContractStatusSchema,
@@ -4451,7 +4591,9 @@ var ContractSchemaRegistry = {
   [SCHEMA_IDS.contextPack]: ContextPackSchema,
   [SCHEMA_IDS.agentTrajectory]: AgentTrajectorySchema,
   [SCHEMA_IDS.validationPlan]: ValidationPlanSchema,
-  [SCHEMA_IDS.proofBundle]: ProofBundleSchema
+  [SCHEMA_IDS.proofBundle]: ProofBundleSchema,
+  [SCHEMA_IDS.scaffoldManifest]: ScaffoldManifestSchema,
+  [SCHEMA_IDS.scaffoldInstallRecord]: ScaffoldInstallRecordSchema
 };
 
 // src/validators.ts

package/examples/scaffold-install-record.invalid.json

@@ -0,0 +1,12 @@
+{
+  "schema": "hasna.scaffold_install_record.v1",
+  "id": "install_scaffold_open_source_invalid",
+  "createdAt": "2026-06-28T16:56:00.000Z",
+  "scaffoldId": "scaffold-open-source",
+  "target": {
+    "kind": "repo",
+    "id": "open-example",
+    "uri": "git+https://github.com/hasna/open-example.git"
+  },
+  "status": "installed"
+}

package/examples/scaffold-install-record.valid.json

@@ -0,0 +1,43 @@
+{
+  "schema": "hasna.scaffold_install_record.v1",
+  "id": "install_scaffold_open_source_001",
+  "createdAt": "2026-06-28T16:56:00.000Z",
+  "scaffoldId": "scaffold-open-source",
+  "scaffoldVersion": "1.0.0",
+  "manifestRef": {
+    "kind": "artifact",
+    "id": "scaffold-open-source-manifest",
+    "uri": "artifact://scaffolds/scaffold-open-source/scaffold.manifest.json"
+  },
+  "target": {
+    "kind": "repo",
+    "id": "open-example",
+    "uri": "git+https://github.com/hasna/open-example.git"
+  },
+  "status": "installed",
+  "installedAt": "2026-06-28T16:56:30.000Z",
+  "installer": {
+    "kind": "agent",
+    "id": "agent_codewith",
+    "name": "Codewith"
+  },
+  "packageManager": "bun",
+  "options": {
+    "includeDashboard": false,
+    "includeMcp": true
+  },
+  "generatedFiles": [
+    {
+      "kind": "file",
+      "id": "package_json",
+      "uri": "repo://open-example/package.json"
+    }
+  ],
+  "evidenceRefs": [
+    {
+      "id": "ev_scaffold_validate",
+      "kind": "command_output",
+      "uri": "artifact://runs/install_scaffold_open_source_001/scaffolds-validate.txt"
+    }
+  ]
+}

package/examples/scaffold-manifest.invalid.json

@@ -0,0 +1,13 @@
+{
+  "schema": "hasna.scaffold_manifest.v1",
+  "id": "scaffold-empty",
+  "createdAt": "2026-06-28T16:55:00.000Z",
+  "name": "scaffold-empty",
+  "version": "1.0.0",
+  "summary": "Invalid active scaffold without output requirements or validation.",
+  "type": "open_source",
+  "status": "active",
+  "output": {
+    "packageManager": "bun"
+  }
+}

package/examples/scaffold-manifest.valid.json

@@ -0,0 +1,62 @@
+{
+  "schema": "hasna.scaffold_manifest.v1",
+  "id": "scaffold-open-source",
+  "createdAt": "2026-06-28T16:55:00.000Z",
+  "name": "scaffold-open-source",
+  "version": "1.0.0",
+  "summary": "Bun and TypeScript CLI/MCP/library package scaffold for public Hasna open-source repos.",
+  "type": "open_source",
+  "status": "active",
+  "capabilities": ["cli", "mcp", "library", "tests", "ci", "docs"],
+  "techStack": ["Bun", "TypeScript", "Commander", "Zod"],
+  "tags": ["open-source", "cli", "mcp", "package"],
+  "source": {
+    "kind": "repo",
+    "id": "hasna_contracts",
+    "uri": "git+https://github.com/hasna/contracts.git"
+  },
+  "output": {
+    "packageManager": "bun",
+    "languages": ["TypeScript"],
+    "requiredFiles": ["package.json", "README.md", "src/index.ts"],
+    "requiredDirectories": ["src", "tests"],
+    "optionalDirectories": ["examples", "docs"]
+  },
+  "env": [
+    {
+      "key": "HASNA_HOME",
+      "description": "Optional Hasna state directory override.",
+      "required": false,
+      "secret": false,
+      "group": "runtime"
+    }
+  ],
+  "scripts": [
+    {
+      "name": "test",
+      "command": "bun test",
+      "description": "Run unit tests.",
+      "required": true
+    },
+    {
+      "name": "typecheck",
+      "command": "tsc --noEmit",
+      "description": "Run TypeScript type checking.",
+      "required": true
+    }
+  ],
+  "validationChecks": [
+    {
+      "id": "typecheck",
+      "kind": "typecheck",
+      "command": "bun run typecheck",
+      "required": true
+    },
+    {
+      "id": "tests",
+      "kind": "test",
+      "command": "bun test",
+      "required": true
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/contracts",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared schemas and validators for Hasna open-source agent infrastructure contracts.",
   "type": "module",
   "license": "Apache-2.0",
@@ -45,12 +45,13 @@
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "lint": "tsc --noEmit",
-    "verify:release": "bun run typecheck && bun test && bun run build && bun run smoke:dist && bun run pack:check",
+    "conformance": "bun run src/cli/index.ts conformance examples",
+    "verify:release": "bun run typecheck && bun test && bun run conformance && bun run build && bun run smoke:dist && bun run pack:check",
     "smoke:dist": "bun scripts/smoke-dist.ts",
-    "pack:check": "npm pack --dry-run --json --ignore-scripts",
+    "pack:check": "bun pm pack --dry-run --ignore-scripts",
     "dev:cli": "bun run src/cli/index.ts",
     "prepack": "bun run verify:release",
-    "prepublishOnly": "bun run typecheck && bun test"
+    "prepublishOnly": "bun run verify:release"
   },
   "keywords": [
     "contracts",