@hasna/contracts 0.1.1 → 0.2.0

package/README.md

@@ -124,6 +124,12 @@ defaults are applied; output aliases such as `EvidenceRef` describe parsed data.
 - `hasna.validation_plan.v1`: deterministic checks a package or agent should run.
 - `hasna.proof_bundle.v1`: reviewable validation result that ties a subject to
   checks, evidence, verifier, and verdict.
+- `hasna.scaffold_manifest.v1`: public, portable description of a scaffold's
+  type, status, capabilities, output shape, env vars, scripts, and validation
+  checks.
+- `hasna.scaffold_install_record.v1`: portable receipt for a scaffold install
+  against a target repo or project, including installer, status, generated
+  resource refs, evidence, and proof refs.
 
 Every top-level contract includes a literal `schema` field. Consumers should
 reject objects whose embedded schema does not match the validator being used.
@@ -176,6 +182,11 @@ helpers. Owning packages still own storage and behavior.
 - `open-evals` owns evaluation execution and scored validation results.
 - `open-economy` owns budget, cost, and usage policy decisions.
 - `open-monitor` owns fleet health classification and alerting.
+- `iapp-scaffolds` owns scaffold templates, registry behavior, install/setup
+  behavior, MCP tools, CLI UX, and private/internal scaffold metadata. It should
+  validate public scaffold manifests and install records with
+  `@hasna/contracts`, but `@hasna/contracts` must not import or execute
+  `iapp-scaffolds`.
 
 ## Downstream Integration Recipes
 
@@ -216,6 +227,10 @@ native domain objects immediately.
 - `open-actions`: keep domain action manifests, but expose shared `ActorRef`,
   `EvidenceRef`, `CapabilityCard`, `DecisionEnvelope`, and `WorkRun` adapter
   views.
+- `iapp-scaffolds`: emit `ScaffoldManifest` documents for bundled templates,
+  write schema-tagged `ScaffoldInstallRecord` receipts for installs, and keep
+  template copying, setup wizards, source paths, and private metadata inside the
+  scaffold package.
 - `open-automations`: keep deterministic app/product automation recipes and
   connector/action recipes. Any agentic task, PR, review, or evaluation flow
   must hand off to OpenLoops rather than creating a second workflow queue.

package/dist/cli/index.js

@@ -6074,7 +6074,7 @@ var coerce = {
 };
 var NEVER = INVALID;
 // src/schemas.ts
-var CONTRACTS_PACKAGE_VERSION = "0.1.1";
+var CONTRACTS_PACKAGE_VERSION = "0.2.0";
 var SCHEMA_IDS = {
   actorRef: "hasna.actor_ref.v1",
   resourceRef: "hasna.resource_ref.v1",
@@ -6086,7 +6086,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();
@@ -6390,6 +6392,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,
@@ -6536,7 +6676,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/dist/index.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.1";
+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
@@ -4533,6 +4675,15 @@ export {
   TagsSchema,
   Sha256DigestSchema,
   SchemaIdSchema,
+  ScaffoldTypeSchema,
+  ScaffoldStatusSchema,
+  ScaffoldScriptSchema,
+  ScaffoldOutputShapeSchema,
+  ScaffoldManifestSchema,
+  ScaffoldInstallStatusSchema,
+  ScaffoldInstallRecordSchema,
+  ScaffoldEnvVarSchema,
+  ScaffoldCapabilitySchema,
   SCHEMA_IDS,
   ResourceRefSchema,
   ResourcePointerSchema,