@icebreakers/monorepo-templates 2.1.0 → 2.2.0

package/assets/package.json

@@ -27,16 +27,12 @@
   },
   "scripts": {
     "build": "turbo run build",
-    "tooling:build": "turbo run build --filter=@icebreakers/monorepo --filter=repoctl",
     "dev": "turbo run dev --concurrency=20",
-    "test": "node -e \"require('node:fs').mkdirSync('coverage/.tmp', { recursive: true })\" && pnpm check:no-tracked-build-artifacts && vitest run && pnpm test:types",
-    "test:packaged-doctor": "node scripts/smoke-packaged-doctor.mjs",
-    "test:dev": "node -e \"require('node:fs').mkdirSync('coverage/.tmp', { recursive: true })\" && pnpm check:no-tracked-build-artifacts && vitest",
-    "lint": "pnpm run tooling:build && turbo run lint",
+    "test": "node -e \"require('node:fs').mkdirSync('coverage/.tmp', { recursive: true })\" && vitest run && pnpm test:types",
+    "test:dev": "node -e \"require('node:fs').mkdirSync('coverage/.tmp', { recursive: true })\" && vitest",
+    "lint": "turbo run lint",
     "tsd": "turbo run tsd",
     "test:types": "turbo run test:types",
-    "check:no-tracked-build-artifacts": "node ./scripts/check-no-tracked-build-artifacts.mjs",
-    "check:workflows": "node ./scripts/check-workflows.mjs",
     "audit": "pnpm audit --audit-level=moderate",
     "audit:fix": "pnpm audit --fix",
     "cf-typegen": "pnpm --filter @icebreakers/client --filter @icebreakers/server run cf-typegen",
@@ -81,11 +77,11 @@
     "lint-staged": "^17.6.0",
     "only-allow": "^1.2.2",
     "repoctl": "latest",
-    "stylelint": "^17.15.0",
+    "stylelint": "^17.16.0",
     "tailwindcss": "^4.3.3",
     "tsd": "^0.33.0",
     "tsdown": "0.23.0",
-    "turbo": "^2.11.5",
+    "turbo": "^2.11.6",
     "typescript": "^6.0.3",
     "vitest": "~5.0.3",
     "yaml": "^2.9.1"

package/assets/pnpm-workspace.yaml

@@ -18,7 +18,8 @@ allowBuilds:
 overrides:
   prettier: 3.9.9
   typescript: 6.0.3
-  vite: 8.3.1
+  "@arethetypeswrong/core>typescript": 5.6.1-rc
+  vite: 8.3.2
   postcss: 8.5.28
   postcss-selector-parser: 7.1.6
   js-yaml: 5.4.2

package/assets/repoctl.config.ts

@@ -31,7 +31,7 @@ export default {
       },
     },
     lintStaged: {
-      monorepoCommand: 'pnpm exec repo',
+      repoCommand: 'pnpm exec repo',
     },
     vitest: {
       includeWorkspaceRootConfig: false,

package/assets/turbo.json

@@ -19,7 +19,8 @@
         "tsconfig*.json",
         "*.config.{js,ts,mjs,mts}",
         "public/**",
-        "nimbus.json"
+        "nimbus.json",
+        "index.html"
       ],
       "outputs": [
         "dist/**",

package/dist/cli.mjs

@@ -1,4 +1,4 @@
-import { t as prepareAssets } from "./prepare-2VvFwYDz.mjs";
+import { t as prepareAssets } from "./prepare-BYNSxvoB.mjs";
 import process from "node:process";
 //#region src/cli.ts
 async function main() {

package/dist/index.d.mts

@@ -1,9 +1,34 @@
 import checkbox from "@inquirer/checkbox";
 import input from "@inquirer/input";
+import password from "@inquirer/password";
 import select from "@inquirer/select";
 import { Command, program } from "commander";
 //#region src/types.d.ts
 type TemplateCategory = 'app' | 'docs' | 'library' | 'service' | 'tool';
+type TemplateRemoteSource = {
+  kind: 'npm';
+  packageName: string;
+  version: string;
+  registry?: string;
+} | {
+  kind: 'git';
+  repository: string;
+  ref: string;
+};
+type ResolvedTemplateRemoteSource = {
+  kind: 'npm';
+  packageName: string;
+  requestedVersion: string;
+  version: string;
+  registry: string;
+  integrity: string;
+} | {
+  kind: 'git';
+  repository: string;
+  requestedRef: string;
+  commit: string;
+  integrity: string;
+};
 interface TemplateChoice {
   key: string;
   label: string;
@@ -15,6 +40,8 @@ interface TemplateChoice {
 interface TemplateDefinition {
   source: string;
   target: string;
+  /** Resolve source relative to this immutable remote asset instead of templatesDir. */
+  remote?: TemplateRemoteSource;
 }
 interface GetTemplateChoicesOptions {
   category?: TemplateCategory;
@@ -40,6 +67,8 @@ interface PrepareAssetsOptions {
 export declare function prepareAssets(options?: PrepareAssetsOptions): Promise<void>;
 //#endregion
 //#region src/runtime-assets.d.ts
+/** Inspect asset readiness without acquiring locks or writing generated files. */
+export declare function areTemplateAssetsPrepared(): Promise<boolean>;
 export declare function ensureTemplateAssetsPrepared(): Promise<void>;
 //#endregion
 //#region src/scaffold.d.ts
@@ -60,6 +89,8 @@ interface ScaffoldWorkspaceOptions {
   includeAssets?: boolean;
   targetMode?: TargetMode;
   force?: boolean;
+  /** Runs caller-owned root transformations before any successful instance registration. */
+  afterScaffold?: () => Promise<void>;
 }
 export declare function scaffoldTemplate(options: ScaffoldTemplateOptions): Promise<void>;
 export declare function scaffoldWorkspace(options: ScaffoldWorkspaceOptions): Promise<void>;
@@ -86,6 +117,255 @@ export declare function isGitignoreFile(name: string): boolean;
 export declare function shouldSkipTemplatePath(rootDir: string, targetPath: string): boolean;
 export declare function createTemplateCopyFilter(rootDir: string): (src: string) => boolean;
 //#endregion
+//#region src/instances/types.d.ts
+interface TemplateSnapshotFile {
+  path: string;
+  content: string;
+  executable: boolean;
+}
+interface TemplateSnapshot {
+  schemaVersion: 1;
+  files: TemplateSnapshotFile[];
+  directories: string[];
+}
+type TemplateGenerationProfile = 'workspace-copy-v1' | 'repo-new-v1' | 'repo-new-parameters-v1';
+/** Only these non-secret inputs are retained; arbitrary config and environment are never serialized. */
+interface TemplateGenerationParameters {
+  packageName?: string;
+  renameJson?: boolean;
+  /** Validated nonsensitive template inputs only. */
+  templateValues?: Record<string, string | boolean>;
+  /** Names only; values are never retained. */
+  sensitiveParameters?: string[];
+}
+interface TemplateInstanceSource {
+  kind: 'package' | 'snapshot' | 'remote';
+  templatePath: string;
+  packageName?: string;
+  version?: string;
+  digest?: string;
+  remote?: ResolvedTemplateRemoteSource;
+}
+type TemplateInstanceBaseline = {
+  status: 'available';
+  original: string;
+  rendered: string;
+} | {
+  status: 'unverified';
+  reason: 'source-unavailable';
+};
+interface TemplateInstance {
+  id: string;
+  target: string;
+  template: string;
+  provenance: 'created' | 'linked';
+  source: TemplateInstanceSource;
+  generator: {
+    profile: TemplateGenerationProfile;
+    version: string;
+  };
+  parameters: TemplateGenerationParameters;
+  baseline: TemplateInstanceBaseline;
+  /** Explicit instance-relative files or directories excluded from future template upgrades. */
+  excludedPaths?: string[];
+}
+interface TemplateInstanceRegistry {
+  schemaVersion: 1;
+  instances: TemplateInstance[];
+}
+interface TemplateInstanceInfo {
+  instance: TemplateInstance;
+  targetStatus: 'present' | 'missing' | 'unsafe';
+  baselineStatus: 'available' | 'unverified' | 'unavailable';
+}
+interface PreparedTemplateSource {
+  source: TemplateInstanceSource;
+  snapshot: TemplateSnapshot;
+}
+interface GeneratedTemplateInstanceOptions {
+  workspaceDir: string;
+  targetDir: string;
+  template: string;
+  preparedSource: PreparedTemplateSource;
+  profile: TemplateGenerationProfile;
+  parameters?: TemplateGenerationParameters;
+  generatorVersion?: string;
+  /** Secret-bearing output files stay outside recorded baselines and later upgrades. */
+  excludedPaths?: string[];
+}
+interface TemplateInstanceDraft {
+  instance: TemplateInstance;
+  snapshots: Record<string, TemplateSnapshot>;
+}
+interface TemplateInstanceRegistrationOptions extends Partial<Pick<TemplateInstanceReplacementHooks, 'rollback' | 'committed'>> {
+  /** Generated path-based IDs may collide after relocation; explicit caller IDs remain strict by default. */
+  allocateIdOnConflict?: boolean;
+}
+/** File-side transaction hooks run while the instance registry lock is held. */
+interface TemplateInstanceReplacementHooks {
+  apply: () => Promise<void>;
+  rollback: () => Promise<void>;
+  committed: () => Promise<void>;
+}
+interface TemplateInstanceMovePlan {
+  from: string;
+  to: string;
+  beforeHash: string;
+  afterHash: string;
+  relocations: {
+    id: string;
+    from: string;
+    to: string;
+  }[];
+}
+interface TemplateFileDifference {
+  path: string;
+  status: 'added' | 'modified' | 'deleted';
+}
+//#endregion
+//#region src/instances/move.d.ts
+/** Preview target changes without treating business edits as a new template baseline. */
+export declare function planTemplateInstanceMove(workspaceDir: string, from: string, to: string): Promise<TemplateInstanceMovePlan>;
+/** Hold the registry lock through file mutation, registry commit and any rollback, including moves with no registered instances. */
+export declare function moveTemplateInstances(workspaceDir: string, plan: TemplateInstanceMovePlan, hooks: TemplateInstanceReplacementHooks, replay?: boolean): Promise<string[]>;
+//#endregion
+//#region src/instances/operations.d.ts
+export declare function templateInstanceId(target: string, template: string): string;
+/** Reserve a new directory only when no existing instance owns its path. */
+export declare function createTemplateInstanceTarget(workspaceDir: string, relative: string): Promise<string>;
+export declare function prepareGeneratedTemplateInstance(options: GeneratedTemplateInstanceOptions): Promise<TemplateInstanceDraft>;
+export declare function recordGeneratedTemplateInstance(options: GeneratedTemplateInstanceOptions): Promise<TemplateInstance>;
+export declare function listTemplateInstances(workspaceDir: string): Promise<TemplateInstanceInfo[]>;
+export declare function rebuildTemplateInstanceBaseline(workspaceDir: string, id: string, targetDir: string, layer?: 'original' | 'rendered'): Promise<TemplateInstance>;
+/** Relocation never guesses based on a package name; all retained baseline files must identify the instance. */
+export declare function relocateTemplateInstance(workspaceDir: string, id: string, target: string, apply?: boolean): Promise<{
+  applied: boolean;
+  instance: TemplateInstance;
+  target: string;
+  changed: boolean;
+}>;
+//#endregion
+//#region src/instances/paths.d.ts
+export declare const templateRegistryPath = ".repoctl/template-instances.json";
+export declare const templateBaselineDirectory = ".repoctl/template-baselines";
+/** Reject links in every existing ancestor, including a missing leaf's parents. */
+export declare function safeInstancePath(workspaceDir: string, relativePath: string): Promise<string>;
+export declare function instanceRelativePath(workspaceDir: string, targetDir: string): string;
+//#endregion
+//#region src/instances/replace.d.ts
+/** Replace exactly one instance, rolling file mutations back before releasing the registry lock on failure. */
+export declare function replaceTemplateInstance(workspaceDir: string, before: TemplateInstance, draft: TemplateInstanceDraft, hooks: TemplateInstanceReplacementHooks): Promise<TemplateInstance>;
+//#endregion
+//#region src/instances/schema.d.ts
+export declare function isExactTemplateVersion(value: string): boolean;
+export declare function normalizeTemplateExclusions(values: string[]): string[];
+export declare function generationParameters(input?: TemplateGenerationParameters): TemplateGenerationParameters;
+//#endregion
+//#region src/instances/snapshot.d.ts
+export declare function snapshotDigest(snapshot: TemplateSnapshot): string;
+/** Capture only template deliverables; never follow symbolic links or collect repository credentials. */
+export declare function captureTemplateSnapshot(directory: string): Promise<TemplateSnapshot>;
+export declare function compareTemplateSnapshots(baseline: TemplateSnapshot, current: TemplateSnapshot): TemplateFileDifference[];
+export declare function writeTemplateSnapshot(snapshot: TemplateSnapshot, targetDir: string): Promise<void>;
+//#endregion
+//#region src/instances/source.d.ts
+export declare function readTemplatePackageVersion(sourcePackageDir?: string): Promise<string>;
+export declare function prepareTemplateInstanceSource(sourceDir: string, historicalPackageDir?: string): Promise<PreparedTemplateSource>;
+//#endregion
+//#region src/instances/store.d.ts
+export declare function loadTemplateInstanceRegistry(workspaceDir: string): Promise<TemplateInstanceRegistry>;
+export declare function loadTemplateBaseline(workspaceDir: string, digest: string): Promise<TemplateSnapshot>;
+export declare function canVerifyTemplateInstance(existing: TemplateInstance, next: TemplateInstance): boolean;
+/** Generated IDs can opt into collision allocation under the lock; retries retain the existing target identity. */
+export declare function registerTemplateInstances(workspaceDir: string, drafts: TemplateInstanceDraft[], precondition?: (registry: TemplateInstanceRegistry) => Promise<void>, options?: TemplateInstanceRegistrationOptions): Promise<TemplateInstance[]>;
+//#endregion
+//#region src/instances/workspace.d.ts
+/** Call after all scaffold and root-manifest transformations have succeeded. */
+export declare function recordWorkspaceTemplateInstances(workspaceDir: string, templateKeys: string[], templatesDir?: string, originals?: Map<string, PreparedTemplateSource>): Promise<TemplateInstance[]>;
+//#endregion
+//#region src/parameters/types.d.ts
+type TemplateParameterValue = string | boolean;
+interface ParameterDetails {
+  description?: string;
+  required?: boolean;
+}
+type TemplateParameterDefinition = ParameterDetails & ({
+  type: 'string';
+  default?: string;
+  sensitive?: boolean;
+} | {
+  type: 'boolean';
+  default?: boolean;
+  sensitive?: false;
+} | {
+  type: 'enum';
+  options: string[];
+  default?: string;
+  sensitive?: false;
+});
+type TemplateParameterSchema = Record<string, TemplateParameterDefinition>;
+type TemplateParameterValues = Record<string, TemplateParameterValue>;
+interface ResolvedTemplateParameters {
+  /** For rendering only. Never put this object in a log or persisted report. */
+  values: TemplateParameterValues;
+  report: TemplateParameterValues;
+  retained: TemplateParameterValues;
+  sensitive: string[];
+}
+interface TemplateParameterCondition {
+  parameter: string;
+  equals: TemplateParameterValue;
+}
+interface TemplateConditionalFiles {
+  when: TemplateParameterCondition;
+  /** Exact source-relative file or directory paths, without expressions or globs. */
+  files?: string[];
+  package?: Partial<Record<'scripts' | 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies', Record<string, string>>>;
+}
+/** Optional repoctl.template.json inside a template source directory. */
+interface TemplateParameterManifest {
+  schemaVersion: 1;
+  parameters: TemplateParameterSchema;
+  /** Only these UTF-8 text files expand {{repoctl:name}} or {{repoctl-json:name}}. */
+  interpolate?: string[];
+  conditions?: TemplateConditionalFiles[];
+}
+//#endregion
+//#region src/parameters/manifest.d.ts
+export declare const templateParameterManifestName = "repoctl.template.json";
+export declare function parseTemplateParameterManifest(value: unknown): TemplateParameterManifest;
+export declare function readTemplateParameterManifest(snapshot: TemplateSnapshot): TemplateParameterManifest | undefined;
+//#endregion
+//#region src/parameters/render.d.ts
+interface TemplateParameterRender {
+  snapshot: TemplateSnapshot;
+  sensitivePaths: string[];
+  files: Array<{
+    path: string;
+    status: 'include' | 'omit';
+    sensitive: boolean;
+  }>;
+  package: Array<{
+    section: string;
+    name: string;
+    status: 'include' | 'omit';
+  }>;
+}
+/** Expand declared text only. Binary files and all undeclared files remain byte-for-byte identical. */
+export declare function renderTemplateParameters(source: TemplateSnapshot, manifest: TemplateParameterManifest, parameters: ResolvedTemplateParameters): TemplateParameterRender;
+//#endregion
+//#region src/parameters/resolve.d.ts
+/** The same strict, synchronous resolver serves prompts, JSON input and local generators. */
+export declare function resolveTemplateParameters(schema: TemplateParameterSchema, input?: unknown): ResolvedTemplateParameters;
+interface TemplateParameterPrompt {
+  (name: string, definition: TemplateParameterSchema[string]): Promise<TemplateParameterValue | undefined>;
+}
+/** Prompts only omitted inputs; supplied inputs are validated before any question is asked. */
+export declare function promptTemplateParameters(schema: TemplateParameterSchema, input: unknown, prompt: TemplateParameterPrompt): Promise<ResolvedTemplateParameters>;
+//#endregion
+//#region src/parameters/schema.d.ts
+export declare function validateTemplateParameterSchema(value: unknown): asserts value is TemplateParameterSchema;
+//#endregion
 //#region src/templates.d.ts
 export declare const templateCategories: readonly ["app", "docs", "library", "service", "tool"];
 export declare function isTemplateCategory(value: string): value is TemplateCategory;
@@ -106,4 +386,4 @@ export declare const templateSourceMap: Record<string, string>;
 export declare const templateTargetMap: Record<string, string>;
 export declare const templateMap: Record<string, string>;
 //#endregion
-export { Command, type GetTemplateChoicesOptions, type SuggestTemplateKeyOptions, type TemplateCategory, type TemplateChoice, type TemplateDefinition, checkbox, input, program, select };
+export { Command, type GeneratedTemplateInstanceOptions, type GetTemplateChoicesOptions, type PreparedTemplateSource, type ResolvedTemplateParameters, type ResolvedTemplateRemoteSource, type SuggestTemplateKeyOptions, type TemplateCategory, type TemplateChoice, type TemplateConditionalFiles, type TemplateDefinition, type TemplateFileDifference, type TemplateGenerationParameters, type TemplateGenerationProfile, type TemplateInstance, type TemplateInstanceBaseline, type TemplateInstanceDraft, type TemplateInstanceInfo, type TemplateInstanceMovePlan, type TemplateInstanceRegistrationOptions, type TemplateInstanceRegistry, type TemplateInstanceReplacementHooks, type TemplateInstanceSource, type TemplateParameterCondition, type TemplateParameterDefinition, type TemplateParameterManifest, type TemplateParameterPrompt, type TemplateParameterRender, type TemplateParameterSchema, type TemplateParameterValue, type TemplateParameterValues, type TemplateRemoteSource, type TemplateSnapshot, type TemplateSnapshotFile, checkbox, input, password, program, select };