@uns-kit/cli 2.0.18 → 2.0.20

package/README.md

@@ -43,9 +43,27 @@ pnpm run dev
 
 When `git` is available on your PATH the scaffold also initializes a fresh repository so you can commit immediately.
 
+### Create from a service bundle
+
+```bash
+uns-kit create --bundle ./service.bundle.json
+uns-kit create --bundle ./service.bundle.json --dest ./my-dir
+uns-kit create --bundle ./service.bundle.json --dest . --allow-existing
+```
+
+Bundle-driven create uses `service.bundle.json` as the source of truth. The CLI:
+
+- scaffolds the base TypeScript app from the existing default template
+- copies the original bundle into the project root as `service.bundle.json`
+- generates `SERVICE_SPEC.md` and `AGENTS.md`
+- applies supported bundle features such as `vscode` and `devops`
+
+When `--bundle` is used, the default destination is `./<metadata.name>`. The TypeScript CLI only accepts bundles with `scaffold.stack = "ts"` and currently supports `scaffold.template = "default"` for this MVP. If the bundle targets Python instead, use `uns-kit-py create --bundle ...`.
+
 ## Commands
 
 - `uns-kit create <name>` – create a new UNS project in the specified directory.
+- `uns-kit create --bundle <path> [--dest <dir>] [--allow-existing]` – create a new TypeScript UNS project from `service.bundle.json`.
 - `uns-kit configure [path] [features...]` – run multiple configure templates in sequence (`--all`, `--overwrite`).
 - `uns-kit configure-templates [path] [templates...]` – copy any template directory (`--all`, `--overwrite`).
 - `uns-kit configure-devops [path]` – add Azure DevOps tooling (dependencies, script, config) to an existing project.

package/dist/index.js

@@ -9,6 +9,7 @@ import process from "node:process";
 import readline from "node:readline/promises";
 import { promisify } from "node:util";
 import * as azdev from "azure-devops-node-api";
+import { generateAgentsMarkdown, generateServiceSpecMarkdown, readAndValidateServiceBundle, } from "./service-bundle.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const require = createRequire(import.meta.url);
@@ -145,14 +146,17 @@ async function main() {
         return;
     }
     if (command === "create") {
-        const projectName = args[1];
-        if (!projectName) {
-            console.error("Missing project name. Example: uns-kit create my-app");
-            process.exitCode = 1;
-            return;
-        }
         try {
-            await createProject(projectName);
+            const createOptions = parseCreateArgs(args.slice(1));
+            if (createOptions.bundlePath) {
+                await createProjectFromBundle(createOptions);
+            }
+            else if (createOptions.projectName) {
+                await createProject(createOptions.projectName);
+            }
+            else {
+                throw new Error("Missing project name. Example: uns-kit create my-app");
+            }
         }
         catch (error) {
             console.error(error.message);
@@ -169,6 +173,7 @@ function printHelp() {
         "\nUsage: uns-kit <command> [options]\n" +
         "\nCommands:\n" +
         "  create <name>           Scaffold a new UNS application\n" +
+        "  create --bundle <path>  Scaffold a new UNS application from service.bundle.json\n" +
         "  configure [dir] [features...] Configure multiple templates (--all, --overwrite)\n" +
         "  configure-templates [dir] [templates...] Copy any template directory (--all, --overwrite)\n" +
         "  configure-devops [dir]  Configure Azure DevOps tooling in an existing project\n" +
@@ -181,25 +186,146 @@ function printHelp() {
         "  configure-uns-reference [dir]  Copy UNS dictionaries (objects/attributes/measurements)\n" +
         "  help                    Show this message\n");
 }
+function parseCreateArgs(args) {
+    let projectName;
+    let bundlePath;
+    let destPath;
+    let allowExisting = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--bundle") {
+            const next = args[index + 1];
+            if (!next || next.startsWith("--")) {
+                throw new Error("Missing value for --bundle.");
+            }
+            bundlePath = next;
+            index += 1;
+            continue;
+        }
+        if (arg === "--dest") {
+            const next = args[index + 1];
+            if (!next || next.startsWith("--")) {
+                throw new Error("Missing value for --dest.");
+            }
+            destPath = next;
+            index += 1;
+            continue;
+        }
+        if (arg === "--allow-existing") {
+            allowExisting = true;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            throw new Error(`Unknown option ${arg}.`);
+        }
+        if (!projectName) {
+            projectName = arg;
+            continue;
+        }
+        throw new Error(`Unexpected argument ${arg}.`);
+    }
+    if (bundlePath && projectName) {
+        throw new Error("Do not pass a positional project name with --bundle. Use --dest to override the target directory.");
+    }
+    if (!bundlePath && destPath) {
+        throw new Error("--dest can only be used with --bundle.");
+    }
+    if (!bundlePath && allowExisting) {
+        throw new Error("--allow-existing can only be used with --bundle.");
+    }
+    return { projectName, bundlePath, destPath, allowExisting };
+}
 async function createProject(projectName) {
     const targetDir = path.resolve(process.cwd(), projectName);
-    await ensureTargetDir(targetDir);
-    const templateDir = path.resolve(__dirname, "../templates/default");
+    const result = await scaffoldTsProject(projectName, targetDir);
+    printTsCreateSuccess(targetDir, result.packageName, initializedGitNextSteps(result.initializedGit, "pnpm run dev"));
+}
+async function createProjectFromBundle(options) {
+    if (!options.bundlePath) {
+        throw new Error("Missing --bundle path.");
+    }
+    const { bundle, raw } = await readAndValidateServiceBundle(options.bundlePath, {
+        expectedStack: "ts",
+        cliName: "uns-kit",
+        counterpartCliName: "uns-kit-py",
+    });
+    const targetDir = path.resolve(process.cwd(), options.destPath ?? bundle.metadata.name);
+    const result = await scaffoldTsProject(bundle.metadata.name, targetDir, {
+        allowExisting: options.allowExisting,
+        templateName: bundle.scaffold.template,
+    });
+    await applyTsBundleFeatures(targetDir, bundle);
+    await writeServiceBundleArtifacts(targetDir, bundle, raw);
+    printTsCreateSuccess(targetDir, result.packageName, initializedGitNextSteps(result.initializedGit, "pnpm run dev"));
+}
+async function scaffoldTsProject(projectName, targetDir, options = {}) {
+    await ensureTargetDir(targetDir, { allowExisting: options.allowExisting });
+    const templateDir = path.resolve(__dirname, `../templates/${options.templateName ?? DEFAULT_TEMPLATE_NAME}`);
+    try {
+        await access(templateDir);
+    }
+    catch (error) {
+        throw new Error(`Template directory is missing: ${templateDir}`);
+    }
     await copyTemplateDirectory(templateDir, targetDir, targetDir);
-    // Seed config examples automatically (previously required configure-config).
     await configureConfigFiles(targetDir, { overwrite: false });
-    const pkgName = normalizePackageName(projectName);
-    await patchPackageJson(targetDir, pkgName);
-    await patchConfigJson(targetDir, pkgName);
-    await replacePlaceholders(targetDir, pkgName);
+    const packageName = normalizePackageName(projectName);
+    await patchPackageJson(targetDir, packageName);
+    await patchConfigJson(targetDir, packageName);
+    await replacePlaceholders(targetDir, packageName);
     const initializedGit = await initGitRepository(targetDir);
-    console.log(`\nCreated ${pkgName} in ${path.relative(process.cwd(), targetDir)}`);
-    console.log("Next steps:");
-    console.log(`  cd ${projectName}`);
-    console.log("  pnpm install");
-    console.log("  pnpm run dev");
+    return { packageName, initializedGit };
+}
+async function applyTsBundleFeatures(targetDir, bundle) {
+    for (const featureName of bundle.scaffold.features) {
+        const resolvedFeature = resolveConfigureFeatureName(featureName);
+        if (resolvedFeature === "devops") {
+            await configureDevopsFromBundle(targetDir, bundle);
+            continue;
+        }
+        const handler = configureFeatureHandlers[resolvedFeature];
+        await handler(targetDir, { overwrite: false });
+    }
+}
+async function configureDevopsFromBundle(targetDir, bundle) {
+    const provider = bundle.repository?.provider?.trim() || AZURE_DEVOPS_PROVIDER;
+    if (provider !== AZURE_DEVOPS_PROVIDER) {
+        throw new Error(`Bundle feature "devops" only supports repository.provider="${AZURE_DEVOPS_PROVIDER}" in this MVP. Received "${provider}".`);
+    }
+    const organization = bundle.repository?.organization?.trim();
+    const project = bundle.repository?.project?.trim();
+    if (!organization || !project) {
+        throw new Error('Bundle feature "devops" requires repository.organization and repository.project for non-interactive scaffolding.');
+    }
+    const result = await applyAzureDevopsConfig(targetDir, {
+        organization,
+        project,
+        overwrite: false,
+        ensureRemote: false,
+    });
+    logDevopsResult(result, { includeRemoteDetails: false });
+}
+async function writeServiceBundleArtifacts(targetDir, bundle, rawBundle) {
+    await writeFile(path.join(targetDir, "service.bundle.json"), rawBundle, "utf8");
+    await writeFile(path.join(targetDir, "SERVICE_SPEC.md"), generateServiceSpecMarkdown(bundle), "utf8");
+    await writeFile(path.join(targetDir, "AGENTS.md"), generateAgentsMarkdown(bundle), "utf8");
+}
+function initializedGitNextSteps(initializedGit, runCommand) {
+    const steps = ["pnpm install", runCommand];
     if (initializedGit) {
-        console.log("  git status  # verify the new repository");
+        steps.push("git status  # verify the new repository");
+    }
+    return steps;
+}
+function printTsCreateSuccess(targetDir, packageName, nextSteps) {
+    const relativeTarget = path.relative(process.cwd(), targetDir) || ".";
+    console.log(`\nCreated ${packageName} in ${relativeTarget}`);
+    console.log("Next steps:");
+    if (relativeTarget !== ".") {
+        console.log(`  cd ${relativeTarget}`);
+    }
+    for (const step of nextSteps) {
+        console.log(`  ${step}`);
     }
 }
 async function initGitRepository(targetDir) {
@@ -250,8 +376,8 @@ async function initGitRepository(targetDir) {
 }
 async function configureDevops(targetPath, options) {
     const targetDir = path.resolve(process.cwd(), targetPath ?? ".");
+    await ensureGitRepository(targetDir);
     const packagePath = path.join(targetDir, "package.json");
-    const configPath = path.join(targetDir, "config.json");
     let pkgRaw;
     try {
         pkgRaw = await readFile(packagePath, "utf8");
@@ -262,6 +388,8 @@ async function configureDevops(targetPath, options) {
         }
         throw error;
     }
+    const pkg = JSON.parse(pkgRaw);
+    const configPath = path.join(targetDir, "config.json");
     let configRaw;
     try {
         configRaw = await readFile(configPath, "utf8");
@@ -272,9 +400,7 @@ async function configureDevops(targetPath, options) {
         }
         throw error;
     }
-    const pkg = JSON.parse(pkgRaw);
     const config = JSON.parse(configRaw);
-    await ensureGitRepository(targetDir);
     const remoteUrl = await getGitRemoteUrl(targetDir, "origin");
     const remoteInfo = remoteUrl ? parseAzureRemote(remoteUrl) : undefined;
     const repositoryName = inferRepositoryNameFromPackage(pkg.name) || inferRepositoryNameFromPackage(path.basename(targetDir));
@@ -282,44 +408,85 @@ async function configureDevops(targetPath, options) {
     const organization = await promptWithDefault(defaultOrganization ? `Azure DevOps organization [${defaultOrganization}]: ` : "Azure DevOps organization: ", defaultOrganization, "Azure DevOps organization is required.");
     const defaultProject = config.devops?.project?.trim() || remoteInfo?.project || "";
     const project = await promptWithDefault(defaultProject ? `Azure DevOps project [${defaultProject}]: ` : "Azure DevOps project: ", defaultProject, "Azure DevOps project is required.");
+    const result = await applyAzureDevopsConfig(targetDir, {
+        organization,
+        project,
+        overwrite: options?.overwrite,
+        ensureRemote: true,
+        repositoryName: remoteInfo?.repository ?? repositoryName,
+    });
+    logDevopsResult(result, { includeRemoteDetails: true });
+}
+async function applyAzureDevopsConfig(targetDir, options) {
+    const packagePath = path.join(targetDir, "package.json");
+    const configPath = path.join(targetDir, "config.json");
+    let pkgRaw;
+    try {
+        pkgRaw = await readFile(packagePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Could not find package.json in ${targetDir}`);
+        }
+        throw error;
+    }
+    let configRaw;
+    try {
+        configRaw = await readFile(configPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Could not find config.json in ${targetDir}`);
+        }
+        throw error;
+    }
+    const pkg = JSON.parse(pkgRaw);
+    const config = JSON.parse(configRaw);
     if (!config.devops || typeof config.devops !== "object") {
         config.devops = {};
     }
     const devopsConfig = config.devops;
     devopsConfig.provider = AZURE_DEVOPS_PROVIDER;
-    devopsConfig.organization = organization;
-    devopsConfig.project = project;
+    devopsConfig.organization = options.organization;
+    devopsConfig.project = options.project;
     let gitRemoteMessage;
     let repositoryUrlMessage;
-    let ensuredRemoteUrl = remoteUrl ?? "";
-    if (!remoteUrl) {
-        const { gitApi } = await resolveAzureGitApi(organization);
-        const repositoryDetails = await ensureAzureRepositoryExists(gitApi, {
-            organization,
-            project,
-            repository: repositoryName,
-        });
-        ensuredRemoteUrl = repositoryDetails.remoteUrl ?? buildAzureGitRemoteUrl(organization, project, repositoryName);
-        await addGitRemote(targetDir, "origin", ensuredRemoteUrl);
-        gitRemoteMessage = `  Added git remote origin -> ${ensuredRemoteUrl}`;
-        const friendlyUrl = repositoryDetails.webUrl ?? buildAzureRepositoryUrl(organization, project, repositoryName);
-        if (friendlyUrl) {
-            repositoryUrlMessage = `  Repository URL: ${friendlyUrl}`;
+    if (options.ensureRemote) {
+        const repositoryName = options.repositoryName
+            ?? inferRepositoryNameFromPackage(pkg.name)
+            ?? inferRepositoryNameFromPackage(path.basename(targetDir));
+        const remoteUrl = await getGitRemoteUrl(targetDir, "origin");
+        const remoteInfo = remoteUrl ? parseAzureRemote(remoteUrl) : undefined;
+        if (!remoteUrl) {
+            const { gitApi } = await resolveAzureGitApi(options.organization);
+            const repositoryDetails = await ensureAzureRepositoryExists(gitApi, {
+                organization: options.organization,
+                project: options.project,
+                repository: repositoryName,
+            });
+            const ensuredRemoteUrl = repositoryDetails.remoteUrl
+                ?? buildAzureGitRemoteUrl(options.organization, options.project, repositoryName);
+            await addGitRemote(targetDir, "origin", ensuredRemoteUrl);
+            gitRemoteMessage = `  Added git remote origin -> ${ensuredRemoteUrl}`;
+            const friendlyUrl = repositoryDetails.webUrl
+                ?? buildAzureRepositoryUrl(options.organization, options.project, repositoryName);
+            if (friendlyUrl) {
+                repositoryUrlMessage = `  Repository URL: ${friendlyUrl}`;
+            }
         }
-    }
-    else {
-        ensuredRemoteUrl = remoteUrl;
-        gitRemoteMessage = `  Git remote origin detected -> ${ensuredRemoteUrl}`;
-        const friendlyUrl = buildAzureRepositoryUrl(remoteInfo?.organization ?? organization, remoteInfo?.project ?? project, remoteInfo?.repository ?? repositoryName);
-        if (friendlyUrl) {
-            repositoryUrlMessage = `  Repository URL: ${friendlyUrl}`;
+        else {
+            gitRemoteMessage = `  Git remote origin detected -> ${remoteUrl}`;
+            const friendlyUrl = buildAzureRepositoryUrl(remoteInfo?.organization ?? options.organization, remoteInfo?.project ?? options.project, remoteInfo?.repository ?? repositoryName);
+            if (friendlyUrl) {
+                repositoryUrlMessage = `  Repository URL: ${friendlyUrl}`;
+            }
         }
     }
     const requiredDevDeps = {
         "azure-devops-node-api": "^15.1.0",
         "simple-git": "^3.27.0",
         "chalk": "^5.4.1",
-        "prettier": "^3.5.3"
+        "prettier": "^3.5.3",
     };
     let pkgChanged = false;
     const devDeps = (pkg.devDependencies ??= {});
@@ -343,10 +510,9 @@ async function configureDevops(targetPath, options) {
         throw new Error("Azure Pipelines template is missing. Please ensure templates/azure-pipelines.yml exists.");
     }
     const pipelineTargetPath = path.join(targetDir, "azure-pipelines.yml");
-    const overwrite = !!options?.overwrite;
     let pipelineMessage = "";
     if (await fileExists(pipelineTargetPath)) {
-        if (overwrite) {
+        if (options.overwrite) {
             await copyFile(azurePipelineTemplatePath, pipelineTargetPath);
             pipelineMessage = "  Overwrote azure-pipelines.yml pipeline definition.";
         }
@@ -362,20 +528,31 @@ async function configureDevops(targetPath, options) {
     if (pkgChanged) {
         await writeFile(packagePath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
     }
+    return {
+        provider: AZURE_DEVOPS_PROVIDER,
+        organization: options.organization,
+        project: options.project,
+        pkgChanged,
+        pipelineMessage,
+        gitRemoteMessage,
+        repositoryUrlMessage,
+    };
+}
+function logDevopsResult(result, options) {
     console.log(`\nDevOps tooling configured.`);
-    console.log(`  DevOps provider: ${AZURE_DEVOPS_PROVIDER}`);
-    console.log(`  Azure organization: ${organization}`);
-    console.log(`  Azure project: ${project}`);
-    if (repositoryUrlMessage) {
-        console.log(repositoryUrlMessage);
+    console.log(`  DevOps provider: ${result.provider}`);
+    console.log(`  Azure organization: ${result.organization}`);
+    console.log(`  Azure project: ${result.project}`);
+    if (options.includeRemoteDetails && result.repositoryUrlMessage) {
+        console.log(result.repositoryUrlMessage);
     }
-    if (gitRemoteMessage) {
-        console.log(gitRemoteMessage);
+    if (options.includeRemoteDetails && result.gitRemoteMessage) {
+        console.log(result.gitRemoteMessage);
     }
-    if (pipelineMessage) {
-        console.log(pipelineMessage);
+    if (result.pipelineMessage) {
+        console.log(result.pipelineMessage);
     }
-    if (pkgChanged) {
+    if (result.pkgChanged) {
         console.log("  Updated package.json scripts/devDependencies. Run pnpm install to fetch new packages.");
     }
     else {
@@ -1204,14 +1381,14 @@ async function fileExists(filePath) {
         throw error;
     }
 }
-async function ensureTargetDir(dir) {
+async function ensureTargetDir(dir, options = {}) {
     try {
         const stats = await stat(dir);
         if (!stats.isDirectory()) {
             throw new Error(`Path ${dir} exists and is not a directory.`);
         }
         const entries = await readdir(dir);
-        if (entries.length > 0) {
+        if (entries.length > 0 && !options.allowExisting) {
             throw new Error(`Directory ${dir} is not empty.`);
         }
     }

package/dist/service-bundle.d.ts

@@ -0,0 +1,55 @@
+export type SupportedBundleStack = "ts" | "python";
+export type ServiceBundle = {
+    schemaVersion: 1;
+    kind: "uns-service-bundle";
+    metadata: {
+        name: string;
+        displayName?: string;
+        serviceType?: string;
+        summary?: string;
+        description?: string;
+        owner?: string;
+        tags: string[];
+    };
+    scaffold: {
+        stack: SupportedBundleStack | string;
+        template: string;
+        features: string[];
+    };
+    repository?: {
+        provider?: string;
+        organization?: string;
+        project?: string;
+        repository?: string;
+        defaultBranch?: string;
+    };
+    domain?: {
+        inputs: unknown[];
+        outputs: unknown[];
+    };
+    docs: {
+        serviceSpec: {
+            goals: string[];
+            nonGoals: string[];
+            acceptanceCriteria: string[];
+        };
+        agents: {
+            projectContext: string[];
+            guardrails: string[];
+            firstTasks: string[];
+            verification: string[];
+        };
+    };
+};
+type ReadBundleOptions = {
+    expectedStack: SupportedBundleStack;
+    cliName: string;
+    counterpartCliName: string;
+};
+export declare function readAndValidateServiceBundle(bundlePath: string, options: ReadBundleOptions): Promise<{
+    bundle: ServiceBundle;
+    raw: string;
+}>;
+export declare function generateServiceSpecMarkdown(bundle: ServiceBundle): string;
+export declare function generateAgentsMarkdown(bundle: ServiceBundle): string;
+export {};

package/dist/service-bundle.js

@@ -0,0 +1,239 @@
+import { readFile } from "node:fs/promises";
+export async function readAndValidateServiceBundle(bundlePath, options) {
+    const raw = await readFile(bundlePath, "utf8");
+    const parsed = parseJsonObject(raw, bundlePath);
+    const bundle = validateServiceBundle(parsed, options);
+    return { bundle, raw };
+}
+export function generateServiceSpecMarkdown(bundle) {
+    const lines = [
+        "# SERVICE_SPEC",
+        "",
+        "> Generated from `service.bundle.json`. Update the bundle as the source of truth.",
+        "",
+        "## Service Identity",
+        ...renderKeyValueList([
+            ["Name", bundle.metadata.name],
+            ["Display Name", bundle.metadata.displayName],
+            ["Service Type", bundle.metadata.serviceType],
+            ["Owner", bundle.metadata.owner],
+            ["Tags", bundle.metadata.tags.length ? bundle.metadata.tags.join(", ") : "None"],
+        ]),
+        "",
+        "## Summary",
+        "",
+        bundle.metadata.summary?.trim() || "Not provided.",
+        "",
+        "## Description",
+        "",
+        bundle.metadata.description?.trim() || "Not provided.",
+        "",
+        "## Scaffold",
+        ...renderKeyValueList([
+            ["Stack", bundle.scaffold.stack],
+            ["Template", bundle.scaffold.template],
+            ["Features", bundle.scaffold.features.length ? bundle.scaffold.features.join(", ") : "None"],
+        ]),
+    ];
+    if (bundle.repository) {
+        lines.push("", "## Repository", ...renderKeyValueList([
+            ["Provider", bundle.repository.provider],
+            ["Organization", bundle.repository.organization],
+            ["Project", bundle.repository.project],
+            ["Repository", bundle.repository.repository],
+            ["Default Branch", bundle.repository.defaultBranch],
+        ]));
+    }
+    if (bundle.domain) {
+        lines.push("", "## Domain Inputs", ...renderUnknownList(bundle.domain.inputs), "", "## Domain Outputs", ...renderUnknownList(bundle.domain.outputs));
+    }
+    lines.push("", "## Goals", ...renderStringList(bundle.docs.serviceSpec.goals), "", "## Non-Goals", ...renderStringList(bundle.docs.serviceSpec.nonGoals), "", "## Acceptance Criteria", ...renderStringList(bundle.docs.serviceSpec.acceptanceCriteria), "");
+    return lines.join("\n");
+}
+export function generateAgentsMarkdown(bundle) {
+    const lines = [
+        "# AGENTS",
+        "",
+        "> This repository was bootstrapped from `service.bundle.json`. Regenerate derived docs from the bundle instead of treating this file as the source of truth.",
+        "",
+        "## Service",
+        ...renderKeyValueList([
+            ["Name", bundle.metadata.name],
+            ["Display Name", bundle.metadata.displayName],
+            ["Stack", bundle.scaffold.stack],
+            ["Template", bundle.scaffold.template],
+        ]),
+        "",
+        "## Project Context",
+        ...renderStringList(bundle.docs.agents.projectContext),
+        "",
+        "## Guardrails",
+        ...renderStringList(bundle.docs.agents.guardrails),
+        "",
+        "## First Tasks",
+        ...renderStringList(bundle.docs.agents.firstTasks),
+        "",
+        "## Verification",
+        ...renderStringList(bundle.docs.agents.verification),
+        "",
+    ];
+    return lines.join("\n");
+}
+function validateServiceBundle(value, options) {
+    const schemaVersion = value.schemaVersion;
+    if (schemaVersion !== 1) {
+        throw new Error(`service bundle schemaVersion must be 1. Received ${JSON.stringify(schemaVersion)}.`);
+    }
+    const kind = value.kind;
+    if (kind !== "uns-service-bundle") {
+        throw new Error(`service bundle kind must be "uns-service-bundle". Received ${JSON.stringify(kind)}.`);
+    }
+    const metadata = requireObject(value.metadata, "metadata");
+    const scaffold = requireObject(value.scaffold, "scaffold");
+    const repository = optionalObject(value.repository, "repository");
+    const domain = optionalObject(value.domain, "domain");
+    const docs = optionalObject(value.docs, "docs");
+    optionalObject(value.provenance, "provenance");
+    const normalized = {
+        schemaVersion: 1,
+        kind: "uns-service-bundle",
+        metadata: {
+            name: requireNonEmptyString(metadata.name, "metadata.name"),
+            displayName: optionalNonEmptyString(metadata.displayName, "metadata.displayName"),
+            serviceType: optionalNonEmptyString(metadata.serviceType, "metadata.serviceType"),
+            summary: optionalNonEmptyString(metadata.summary, "metadata.summary"),
+            description: optionalNonEmptyString(metadata.description, "metadata.description"),
+            owner: optionalNonEmptyString(metadata.owner, "metadata.owner"),
+            tags: optionalStringArray(metadata.tags, "metadata.tags"),
+        },
+        scaffold: {
+            stack: requireNonEmptyString(scaffold.stack, "scaffold.stack"),
+            template: requireNonEmptyString(scaffold.template, "scaffold.template"),
+            features: dedupeStrings(optionalStringArray(scaffold.features, "scaffold.features")),
+        },
+        repository: repository
+            ? {
+                provider: optionalNonEmptyString(repository.provider, "repository.provider"),
+                organization: optionalNonEmptyString(repository.organization, "repository.organization"),
+                project: optionalNonEmptyString(repository.project, "repository.project"),
+                repository: optionalNonEmptyString(repository.repository, "repository.repository"),
+                defaultBranch: optionalNonEmptyString(repository.defaultBranch, "repository.defaultBranch"),
+            }
+            : undefined,
+        domain: domain
+            ? {
+                inputs: optionalUnknownArray(domain.inputs, "domain.inputs"),
+                outputs: optionalUnknownArray(domain.outputs, "domain.outputs"),
+            }
+            : undefined,
+        docs: {
+            serviceSpec: normalizeServiceSpecDocs(optionalObject(docs?.serviceSpec, "docs.serviceSpec")),
+            agents: normalizeAgentsDocs(optionalObject(docs?.agents, "docs.agents")),
+        },
+    };
+    if (normalized.scaffold.stack !== options.expectedStack) {
+        throw new Error(`Bundle scaffold.stack is "${normalized.scaffold.stack}". Use ${options.counterpartCliName} create --bundle <path> instead of ${options.cliName}.`);
+    }
+    if (normalized.scaffold.template !== "default") {
+        throw new Error(`Bundle scaffold.template must be "default" for this MVP. Received "${normalized.scaffold.template}".`);
+    }
+    return normalized;
+}
+function normalizeServiceSpecDocs(value) {
+    return {
+        goals: optionalStringArray(value?.goals, "docs.serviceSpec.goals"),
+        nonGoals: optionalStringArray(value?.nonGoals, "docs.serviceSpec.nonGoals"),
+        acceptanceCriteria: optionalStringArray(value?.acceptanceCriteria, "docs.serviceSpec.acceptanceCriteria"),
+    };
+}
+function normalizeAgentsDocs(value) {
+    return {
+        projectContext: optionalStringArray(value?.projectContext, "docs.agents.projectContext"),
+        guardrails: optionalStringArray(value?.guardrails, "docs.agents.guardrails"),
+        firstTasks: optionalStringArray(value?.firstTasks, "docs.agents.firstTasks"),
+        verification: optionalStringArray(value?.verification, "docs.agents.verification"),
+    };
+}
+function parseJsonObject(raw, bundlePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse bundle JSON at ${bundlePath}: ${error.message}`);
+    }
+    return requireObject(parsed, "bundle");
+}
+function requireObject(value, path) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${path} must be an object.`);
+    }
+    return value;
+}
+function optionalObject(value, path) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    return requireObject(value, path);
+}
+function requireNonEmptyString(value, path) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${path} is required and must be a non-empty string.`);
+    }
+    return value.trim();
+}
+function optionalNonEmptyString(value, path) {
+    if (value === undefined || value === null || value === "") {
+        return undefined;
+    }
+    return requireNonEmptyString(value, path);
+}
+function optionalStringArray(value, path) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${path} must be an array of strings.`);
+    }
+    return value.map((item, index) => requireNonEmptyString(item, `${path}[${index}]`));
+}
+function optionalUnknownArray(value, path) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${path} must be an array.`);
+    }
+    return value;
+}
+function dedupeStrings(values) {
+    const seen = new Set();
+    const deduped = [];
+    for (const value of values) {
+        if (!seen.has(value)) {
+            seen.add(value);
+            deduped.push(value);
+        }
+    }
+    return deduped;
+}
+function renderKeyValueList(entries) {
+    return entries.map(([label, value]) => `- ${label}: ${value && value.trim() ? value : "Not specified"}`);
+}
+function renderStringList(items) {
+    if (!items.length) {
+        return ["- None specified."];
+    }
+    return items.map((item) => `- ${item}`);
+}
+function renderUnknownList(items) {
+    if (!items.length) {
+        return ["- None specified."];
+    }
+    return items.map((item) => {
+        if (typeof item === "string" && item.trim()) {
+            return `- ${item}`;
+        }
+        return `- \`${JSON.stringify(item)}\``;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uns-kit/cli",
-  "version": "2.0.18",
+  "version": "2.0.20",
   "description": "Command line scaffolding tool for UNS applications",
   "type": "module",
   "license": "MIT",
@@ -26,13 +26,13 @@
   ],
   "dependencies": {
     "azure-devops-node-api": "^15.1.1",
-    "@uns-kit/core": "2.0.18"
+    "@uns-kit/core": "2.0.20"
   },
   "unsKitPackages": {
-    "@uns-kit/core": "2.0.18",
-    "@uns-kit/api": "2.0.18",
-    "@uns-kit/cron": "2.0.18",
-    "@uns-kit/temporal": "2.0.18"
+    "@uns-kit/core": "2.0.20",
+    "@uns-kit/api": "2.0.20",
+    "@uns-kit/cron": "2.0.20",
+    "@uns-kit/temporal": "2.0.20"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",