@icebreakers/monorepo-templates 2.1.0 → 2.2.1

package/templates/react-lib/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@icebreakers/react-lib-template",
+  "type": "module",
+  "version": "0.0.0",
+  "private": true,
+  "description": "React component library with explicit JavaScript, types and CSS exports",
+  "license": "MIT",
+  "sideEffects": ["**/*.css"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./style.css": "./dist/style.css"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["LICENSE", "README.md", "dist"],
+  "engines": { "node": ">=22.13.0" },
+  "scripts": {
+    "build": "vite build",
+    "lint": "eslint . && stylelint \"src/**/*.css\"",
+    "lint:fix": "eslint . --fix && stylelint \"src/**/*.css\" --fix",
+    "typecheck": "tsc -b",
+    "tsd": "tsd --files test-d/**/*.test-d.ts",
+    "test": "vitest run",
+    "test:dev": "vitest"
+  },
+  "peerDependencies": {
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "jsdom": "^30.1.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tsd": "^0.33.0",
+    "typescript": "~6.0.3",
+    "vite": "^8.3.2",
+    "vite-plugin-dts": "^5.1.1",
+    "vitest": "~5.0.3"
+  }
+}

package/templates/react-lib/src/counter.tsx

@@ -0,0 +1,28 @@
+import { useState } from 'react'
+import './style.css'
+
+export interface CounterProps {
+  /** Accessible name for this counter's current value. */
+  label?: string
+  /** Initial value, also used by the reset action. */
+  initialCount?: number
+  step?: number
+  disabled?: boolean
+  onCountChange?: (count: number) => void
+}
+
+export function Counter({ label = 'Count', initialCount = 0, step = 1, disabled = false, onCountChange }: CounterProps) {
+  const [count, setCount] = useState(initialCount)
+  function update(next: number) {
+    setCount(next)
+    onCountChange?.(next)
+  }
+
+  return (
+    <div className="repoctl-counter">
+      <output aria-label={label} aria-live="polite">{count}</output>
+      <button type="button" disabled={disabled} onClick={() => update(count + step)}>Increase</button>
+      <button type="button" disabled={disabled || count === initialCount} onClick={() => update(initialCount)}>Reset</button>
+    </div>
+  )
+}

package/templates/react-lib/src/index.ts

@@ -0,0 +1,2 @@
+export { Counter } from './counter.js'
+export type { CounterProps } from './counter.js'

package/templates/react-lib/src/style.css

@@ -0,0 +1,36 @@
+.repoctl-counter {
+  display: inline-flex;
+  gap: 0.75rem;
+  align-items: center;
+  padding: 1rem;
+  font: inherit;
+  color: #14283a;
+  border: 1px solid #ccd4dc;
+  border-radius: 0.75rem;
+}
+
+.repoctl-counter output {
+  min-width: 2ch;
+  font-variant-numeric: tabular-nums;
+  text-align: center;
+}
+
+.repoctl-counter button {
+  padding: 0.5rem 0.75rem;
+  font: inherit;
+  color: #fff;
+  cursor: pointer;
+  background: #14283a;
+  border: 0;
+  border-radius: 0.375rem;
+}
+
+.repoctl-counter button:focus-visible {
+  outline: 2px solid #176bb4;
+  outline-offset: 3px;
+}
+
+.repoctl-counter button:disabled {
+  cursor: default;
+  opacity: 0.5;
+}

package/templates/react-lib/stylelint.config.js

@@ -0,0 +1,3 @@
+import { defineStylelintConfig } from 'repoctl/tooling'
+
+export default await defineStylelintConfig()

package/templates/react-lib/test/counter.test.tsx

@@ -0,0 +1,28 @@
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, expect, it, vi } from 'vitest'
+import { Counter } from '..'
+
+afterEach(cleanup)
+
+it('uses the built public entry to update, notify and reset the initial value', () => {
+  const onCountChange = vi.fn()
+  render(<Counter label="Items" initialCount={3} step={2} onCountChange={onCountChange} />)
+  const count = screen.getByLabelText('Items')
+  const reset = screen.getByRole('button', { name: 'Reset' })
+  expect(count.textContent).toBe('3')
+  expect(reset.hasAttribute('disabled')).toBe(true)
+  fireEvent.click(screen.getByRole('button', { name: 'Increase' }))
+  expect(count.textContent).toBe('5')
+  expect(onCountChange).toHaveBeenLastCalledWith(5)
+  fireEvent.click(reset)
+  expect(count.textContent).toBe('3')
+  expect(onCountChange).toHaveBeenLastCalledWith(3)
+})
+
+it('prevents changes when disabled', () => {
+  const onCountChange = vi.fn()
+  render(<Counter disabled onCountChange={onCountChange} />)
+  fireEvent.click(screen.getByRole('button', { name: 'Increase' }))
+  expect(screen.getByLabelText('Count').textContent).toBe('0')
+  expect(onCountChange).not.toHaveBeenCalled()
+})

package/templates/react-lib/test-d/index.test-d.ts

@@ -0,0 +1,11 @@
+import type { ComponentProps, ReactElement } from 'react'
+import type { CounterProps } from '..'
+import { createElement } from 'react'
+import { expectAssignable, expectError, expectType } from 'tsd'
+import { Counter } from '..'
+
+expectAssignable<CounterProps>({ initialCount: 2, step: 3, onCountChange: count => expectType<number>(count) })
+expectAssignable<ComponentProps<typeof Counter>>({ label: 'Items', disabled: true })
+expectAssignable<ReactElement<CounterProps>>(createElement(Counter, { initialCount: 2 }))
+expectError(createElement(Counter, { initialCount: '2' }))
+expectError(createElement(Counter, { onCountChange: (value: string) => value }))

package/templates/react-lib/tsconfig.app.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2022",
+    "jsx": "react-jsx",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"],
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "verbatimModuleSyntax": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src", "test"]
+}

package/templates/react-lib/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.app.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": false,
+    "emitDeclarationOnly": true,
+    "noEmit": false,
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/templates/react-lib/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }],
+  "files": []
+}

package/templates/react-lib/tsconfig.node.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "types": ["node"],
+    "verbatimModuleSyntax": true
+  },
+  "include": ["vite.config.ts", "vitest.config.ts"]
+}

package/templates/react-lib/vite.config.ts

@@ -0,0 +1,22 @@
+import path from 'node:path'
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+import dts from 'vite-plugin-dts'
+
+export default defineConfig({
+  plugins: [react(), dts({ tsconfigPath: './tsconfig.build.json', entryRoot: './src', clearPureImport: true })],
+  build: {
+    lib: {
+      entry: path.resolve(import.meta.dirname, 'src/index.ts'),
+      formats: ['es'],
+      fileName: 'index',
+      cssFileName: 'style',
+    },
+    rolldownOptions: {
+      // Include JSX runtimes and every peer subpath in the external boundary.
+      external: id => /^(?:react|react-dom)(?:\/|$)/u.test(id),
+      // Counter is a client component; preserve its boundary in bundled RSC consumers.
+      output: { banner: '\'use client\';' },
+    },
+  },
+})

package/templates/react-lib/vitest.config.ts

@@ -0,0 +1,5 @@
+import { defineVitestProjectConfig } from 'repoctl/tooling'
+
+export default await defineVitestProjectConfig({
+  options: { environment: 'jsdom' },
+})

package/templates/react-vite/README.md

@@ -0,0 +1,27 @@
+# React application
+
+A small React and TypeScript SPA built with Vite. It includes an accessible counter, a Vitest interaction test, and the workspace's shared ESLint and Stylelint configuration.
+
+From the workspace root, enable the declared package manager and install dependencies:
+
+```sh
+corepack enable
+pnpm install
+```
+
+Run these commands from this application directory:
+
+```sh
+pnpm dev
+pnpm build
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm preview
+```
+
+`build` creates `dist/`; `preview` serves that production output locally. `lint` checks both code and CSS. `typecheck` uses TypeScript project references for the app, tests, and Vite configuration.
+
+To consume another workspace package, add it as a `workspace:*` dependency, import its package name, and build its public output first. Running `pnpm build` at the workspace root lets Turbo order dependency builds. Do not import another package's `src/` directory.
+
+Router, state management, backend, and CSS framework choices are left to your application.

package/templates/react-vite/eslint.config.js

@@ -0,0 +1,5 @@
+import { defineEslintConfig } from 'repoctl/tooling'
+
+export default await defineEslintConfig({
+  options: { react: true, typescript: true },
+})

package/templates/react-vite/gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+coverage
+*.tsbuildinfo
+.env.local
+.env.*.local

package/templates/react-vite/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="A small React application, ready to make your own." />
+    <title>React workspace</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/react-vite/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@icebreakers/react-vite-template",
+  "type": "module",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Internal React, Vite and TypeScript application template shipped with repoctl",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint . && stylelint \"src/**/*.css\"",
+    "lint:fix": "eslint . --fix && stylelint \"src/**/*.css\" --fix",
+    "typecheck": "tsc -b",
+    "test": "vitest run",
+    "test:dev": "vitest"
+  },
+  "dependencies": {
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "jsdom": "^30.1.1",
+    "typescript": "~6.0.3",
+    "vite": "^8.3.2",
+    "vitest": "~5.0.3"
+  }
+}

package/templates/react-vite/src/app.tsx

@@ -0,0 +1,22 @@
+import { useState } from 'react'
+
+export default function App() {
+  const [count, setCount] = useState(0)
+
+  return (
+    <main>
+      <p className="eyebrow">Your next idea starts here</p>
+      <h1>Make something useful.</h1>
+      <p className="intro">A small React workspace with room to grow.</p>
+      <section className="counter" aria-labelledby="counter-title">
+        <h2 id="counter-title">Try an interaction</h2>
+        <output aria-label="Count" aria-live="polite">{count}</output>
+        <div className="actions">
+          <button type="button" onClick={() => setCount(value => value + 1)}>Add one</button>
+          <button type="button" className="secondary" disabled={count === 0} onClick={() => setCount(0)}>Reset</button>
+        </div>
+      </section>
+      <p className="footnote">Built with React, TypeScript, and Vite.</p>
+    </main>
+  )
+}

package/templates/react-vite/src/main.tsx

@@ -0,0 +1,15 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import App from './app'
+import './style.css'
+
+const container = document.getElementById('root')
+if (!container) {
+  throw new Error('The application root element is missing.')
+}
+
+createRoot(container).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

package/templates/react-vite/src/style.css

@@ -0,0 +1,95 @@
+:root {
+  font-family: system-ui, sans-serif;
+  font-synthesis: none;
+  color: #203834;
+  background: #f5f4ee;
+  text-rendering: optimizelegibility;
+  -webkit-font-smoothing: antialiased;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  min-width: 320px;
+  margin: 0;
+}
+
+main {
+  max-width: 760px;
+  padding: clamp(32px, 10vw, 96px) 24px;
+  margin: 0 auto;
+}
+
+.eyebrow,
+.footnote {
+  font-size: 14px;
+  color: #53655f;
+}
+
+h1 {
+  max-width: 600px;
+  margin: 24px 0;
+  font-size: clamp(40px, 8vw, 72px);
+  line-height: 1.05;
+  letter-spacing: -0.045em;
+}
+
+.intro {
+  font-size: 18px;
+  line-height: 1.6;
+}
+
+.counter {
+  padding: 28px;
+  margin: 40px 0 28px;
+  background: #fffefa;
+  border: 1px solid #c9d3ca;
+  border-radius: 12px;
+}
+
+h2 {
+  margin: 0;
+  font-size: 18px;
+  font-weight: 500;
+}
+
+output {
+  display: block;
+  margin: 16px 0;
+  font-size: 64px;
+  font-variant-numeric: tabular-nums;
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+}
+
+button {
+  min-height: 44px;
+  padding: 10px 20px;
+  font: inherit;
+  color: #fff;
+  cursor: pointer;
+  background: #245e50;
+  border: 1px solid #245e50;
+  border-radius: 6px;
+}
+
+button.secondary {
+  color: #245e50;
+  background: transparent;
+}
+
+button:focus-visible {
+  outline: 3px solid #ba5a20;
+  outline-offset: 4px;
+}
+
+button:disabled {
+  cursor: default;
+  opacity: 0.5;
+}

package/templates/react-vite/stylelint.config.js

@@ -0,0 +1,3 @@
+import { defineStylelintConfig } from 'repoctl/tooling'
+
+export default await defineStylelintConfig()

package/templates/react-vite/test/app.test.tsx

@@ -0,0 +1,22 @@
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, expect, it } from 'vitest'
+import App from '../src/app'
+
+afterEach(cleanup)
+
+it('increments the count and resets it to zero', () => {
+  render(<App />)
+  const count = screen.getByLabelText('Count')
+  const reset = screen.getByRole('button', { name: 'Reset' })
+  expect(count.textContent).toBe('0')
+  expect(reset.hasAttribute('disabled')).toBe(true)
+
+  fireEvent.click(screen.getByRole('button', { name: 'Add one' }))
+  fireEvent.click(screen.getByRole('button', { name: 'Add one' }))
+  expect(count.textContent).toBe('2')
+  expect(reset.hasAttribute('disabled')).toBe(false)
+
+  fireEvent.click(reset)
+  expect(count.textContent).toBe('0')
+  expect(reset.hasAttribute('disabled')).toBe(true)
+})

package/templates/react-vite/tsconfig.app.json

@@ -0,0 +1,26 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2022",
+    "jsx": "react-jsx",
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": [
+      "vite/client"
+    ],
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": [
+    "src",
+    "test"
+  ]
+}

package/templates/react-vite/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    },
+    {
+      "path": "./tsconfig.node.json"
+    }
+  ],
+  "files": []
+}

package/templates/react-vite/tsconfig.node.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2023",
+    "lib": [
+      "ES2023"
+    ],
+    "types": [
+      "node"
+    ],
+    "verbatimModuleSyntax": true
+  },
+  "include": [
+    "vite.config.ts",
+    "vitest.config.ts"
+  ]
+}

package/templates/react-vite/vite.config.ts

@@ -0,0 +1,6 @@
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [react()],
+})

package/templates/react-vite/vitest.config.ts

@@ -0,0 +1,9 @@
+import react from '@vitejs/plugin-react'
+import { defineVitestProjectConfig } from 'repoctl/tooling'
+import { mergeConfig } from 'vitest/config'
+
+export default mergeConfig(await defineVitestProjectConfig({
+  options: { environment: 'jsdom' },
+}), {
+  plugins: [react()],
+})

package/templates/vitepress/.vitepress/navigation/routes.ts

@@ -52,7 +52,14 @@ export const routeSections = [
     items: [
       item('', 'Reference overview', '参考总览'),
       item('commands', 'Command reference', '命令参考'),
+      item('devcontainer', 'Dev Container preset', 'Dev Container 预设'),
       item('config', 'Configuration', '配置文件'),
+      item('organization-presets', 'Organization presets', '组织工程预设'),
+      item('dependencies', 'Dependency consistency', '依赖版本一致性'),
+      item('knip', 'Unused code and dependencies', '闲置代码与依赖检查'),
+      item('artifacts', 'Build and production artifacts', '构建与生产产物'),
+      item('move', 'Move or rename a workspace', '移动或重命名工作区'),
+      item('removal', 'Remove a workspace safely', '安全移除工作区'),
       item('execution-model', 'Execution model', '执行模型'),
       item('output', 'Output formats', '输出格式'),
       item('aliases', 'Command aliases', '命令别名'),

package/templates/vitepress/reference/artifacts.md

@@ -0,0 +1,51 @@
+# Prepare build and production artifacts
+
+`repo workspace prepare` previews one exact package. `prune` invokes locally installed Turbo 2 to produce a partial monorepo and pruned lockfile. `deploy` invokes the exact pnpm version pinned in the root `packageManager` to prepare a production directory. It prepares local files; it does not run the application, build an image or contact a deployment platform.
+
+```sh
+# Build inputs and runtime entrypoints explicitly first.
+pnpm build
+repo workspace prepare @acme/service --mode prune --out ../service-build --json > ../prune-plan.json
+repo workspace prepare --apply ../prune-plan.json
+
+# Split Turbo's output into full/json Docker cache layers.
+repo workspace prepare ./apps/service --mode prune --docker --out ../docker-context --json
+
+# Production workspace dependencies; use only packages already in the local store.
+repo workspace prepare @acme/service --mode deploy --entry dist/server.js --offline --out ../service-runtime --json > ../deploy-plan.json
+repo workspace prepare --apply ../deploy-plan.json
+```
+
+Preview is always read-only, including `--dry-run`; native version, capability and path-setting probes do not install tools. Save the JSON plan outside the source workspace. Applying requires a separate `--apply` command and cannot be combined with preview selections or `--dry-run`.
+
+## Native behavior and prerequisites
+
+Both modes require a pnpm workspace and existing `pnpm-lock.yaml`. Select one uniquely named non-root package by exact npm name or `./directory`; globs, multiple matches and dependency selectors are rejected. The output must be outside the source workspace under an existing directory. Linked, overlapping and unrelated nonempty targets are rejected; there is no force flag.
+
+Prune supports locally installed stable Turbo 2 and keeps native build dependency selection. `manifestCandidates` only explains manifest relationships; Turbo decides what is retained. Native task-dependency and global-file behavior follows the selected Turbo version and configuration. `--docker` retains its native `full`, `json` and lockfile layout.
+
+Deploy supports pinned stable pnpm 10, 11 and 12 when their native command exposes the supported options. It uses `--prod`, `--ignore-scripts`, `--frozen-lockfile` and disables pnpmfile hooks. `--legacy` explicitly selects native legacy behavior, whose production layout may omit a root lockfile; only prune requires that output file. Since pnpm 12.2, native deploy supports non-injected workspace dependencies; earlier versions may require `injectWorkspacePackages` or legacy mode. Peer ambiguity and other native errors remain failures with their native diagnostic code. repoctl does not resolve or rewrite dependency graphs or lockfiles itself.
+
+Deploy checks an existing built runtime file: explicit `--entry`, `package.main`, or a single `bin`. If native `files`/ignore rules omit it, preparation fails. Arbitrary `start` scripts are not interpreted or executed. Native dependency lifecycle scripts stay disabled, so prepare required native binaries explicitly before deployment; artifact preparation does not certify arbitrary application behavior.
+
+## Source and output boundaries
+
+Native tools run against an isolated source copy, without source `node_modules`, `.git`, `.turbo` or `.repoctl` storage. Real `.env`/`.env.*`, `.npmrc`, `.netrc`, `_netrc`, Yarn authentication configuration, `.aws`, `.ssh` and `.gnupg` paths are excluded before copying. Public `.env.example` and `.env.sample` files remain. The output is checked again for these paths. This is a named-file policy, not a general secret detector; use public placeholders in example files and provide deployment credentials separately.
+
+The source copy retains built files even if Git ignores them; native prune/package file rules still control final inclusion. Source symlinks and special files are rejected. Input and output inventories are bounded to 100,000 entries and 1 GiB. Use native tools directly when a workspace needs different copy or storage policies.
+
+Effective pnpm store/cache/state/module/lockfile paths are inspected without dumping credential-bearing configuration. Paths that would write back into the source workspace are rejected before deploy, and module/lockfile storage must remain relative to the artifact. Staging itself must be outside the source workspace. Native global stores outside the workspace remain under pnpm's control.
+
+Output links must resolve inside the artifact. Relative links are preserved; Windows directory junctions are recreated against the final artifact directory. When transferring a Windows artifact, use a copy/archive method that materializes junction contents. Integration tests copy the directory, remove the source and original artifact, then execute the production entry independently.
+
+## Review, recovery and repeated application
+
+Plans fingerprint source files, modes, tool/version evidence, relevant path settings and options. Apply reconstructs the plan and rejects changes. Source inputs are rechecked after copying, after native execution, during publication and before completion. Concurrent source edits are preserved.
+
+Native output is staged first. Publication creates files exclusively, records their ownership and written contents, and commits `.repoctl-artifact.json` last. Files may be visible before the receipt commits; do not consume an incomplete directory. Failures remove only unchanged operation-owned output and retain concurrent edits with their exact paths in the error. Cleanup failure after successful publication returns `cleanupPending` rather than claiming rollback.
+
+Reapplying an unchanged plan returns `unchanged` only if its complete receipt and file inventory still match. Unknown or modified nonempty output is never overwritten. The `.repoctl/workspace-artifacts.lock` covers replay checks through native execution, publication and cleanup. After a crash, confirm no writer remains, inspect incomplete output and retained staging paths, and recover them before removing the lock.
+
+Public APIs: `planWorkspaceArtifact(cwd, options)` and `applyWorkspaceArtifactPlan(cwd, plan, { signal, timeoutMs })`; JSON schema version is 1. Native execution defaults to a two-minute timeout, configurable up to ten minutes through the API.
+
+References: [Turbo prune](https://turborepo.com/docs/reference/prune) and [pnpm deploy](https://pnpm.io/cli/deploy).