coreslopper 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coreslopper",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "description": "An open-source, Claude Code-native workflow for producing music videos from brief to render.",

package/runtime/.github/workflows/ci.yml

@@ -14,14 +14,14 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: 22
           cache: npm
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
 
@@ -29,7 +29,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y ffmpeg
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v10.3.3
 
       - name: Install Node dependencies
         run: npm ci
@@ -56,7 +56,7 @@ jobs:
         run: npm run cli -- contact-sheet projects/demo
 
       - name: Cache Remotion browser
-        uses: actions/cache@v4
+        uses: actions/cache@v6
         with:
           path: ~/.cache/remotion
           key: remotion-browser-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
@@ -79,10 +79,12 @@ jobs:
           TARBALL=$(ls "$RUNNER_TEMP"/pkg/coreslopper-*.tgz)
           npx -y -p "$TARBALL" coreslopper init "$RUNNER_TEMP/coreslopper-npx" --yes --no-install --no-git --skip-project
           npx -y -p "$TARBALL" coreslopper doctor "$RUNNER_TEMP/coreslopper-npx"
+          npx -y -p "$TARBALL" coreslopper update "$RUNNER_TEMP/coreslopper-npx" --no-install | tee "$RUNNER_TEMP/update.log"
+          grep -q "already up to date" "$RUNNER_TEMP/update.log"
           test -f "$RUNNER_TEMP/coreslopper-npx/packages/cli/src/init.ts"
 
       - name: Upload demo artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: demo-artifacts
           path: |

package/runtime/.github/workflows/release.yml

@@ -22,7 +22,7 @@ jobs:
       release_created: ${{ steps.release.outputs.release_created }}
       tag_name: ${{ steps.release.outputs.tag_name }}
     steps:
-      - uses: googleapis/release-please-action@v4
+      - uses: googleapis/release-please-action@v5
         id: release
         with:
           config-file: release-please-config.json
@@ -39,12 +39,12 @@ jobs:
       contents: read
       id-token: write # npm trusted publishing (OIDC) and provenance
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           ref: ${{ needs.release-please.outputs.tag_name || github.ref }}
 
       # Node 24 ships npm 11, which supports npm trusted publishing.
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: 24
           registry-url: https://registry.npmjs.org

package/runtime/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.1.0"}
+{".":"0.2.0"}

package/runtime/AGENTS.md

@@ -131,6 +131,7 @@ npm run schema
 | `npm run cli -- validate-file <file>` | Validate one changed artifact (used by the hook). |
 | `npm run cli -- doctor` | Check workspace, tools, fonts, Remotion, and keys. |
 | `npx coreslopper init [dir]` | Create a workspace, install tools, configure fal.ai, Higgsfield, and Suno. |
+| `npx coreslopper@latest update [dir]` | Update a workspace to the latest workflow; keeps local edits (`--dry-run`, `--force`). |
 | `npx coreslopper doctor` | Check a workspace from outside it. |
 | `npx coreslopper new <slug> --budget <usd>` | Create a project inside a workspace. |
 | `npm run build` | Build `runtime/` and the npx bundle in `dist/`. |
@@ -140,7 +141,7 @@ In Claude Code: `/new-video`, `/video-next`, `/video-status`.
 
 ## Distribution
 
-The root package is published as `coreslopper`. `npm run build` copies the tracked workflow into `runtime/` and bundles `packages/cli/src/npx.ts` into `dist/cli.js`; `prepack` runs the same build. The npm package ships the onboarding CLI (init, doctor, new, status, validate) plus the runtime snapshot, not the Remotion dependency tree. `npx coreslopper init` copies `runtime/` into a private workspace, then the workspace's own `npm install` provides rendering and audio-analysis dependencies. Never publish generated media or `.env`.
+The root package is published as `coreslopper`. `npm run build` copies the tracked workflow into `runtime/` and bundles `packages/cli/src/npx.ts` into `dist/cli.js`; `prepack` runs the same build. The npm package ships the onboarding CLI (init, update, doctor, new, status, validate) plus the runtime snapshot, not the Remotion dependency tree. `npx coreslopper init` copies `runtime/` into a private workspace, then the workspace's own `npm install` provides rendering and audio-analysis dependencies. Never publish generated media or `.env`.
 
 ## Skills
 

package/runtime/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.2.0](https://github.com/hemi1986/coreslopper/compare/v0.1.0...v0.2.0) (2026-11-08)
+
+
+### Features
+
+* add `coreslopper update` to merge a newer workflow into a workspace ([3eddb5c](https://github.com/hemi1986/coreslopper/commit/3eddb5caa64a534a9bf21ca13d45d24c747976e3))
+* add `coreslopper update` to merge a newer workflow into a workspace ([1d10ffd](https://github.com/hemi1986/coreslopper/commit/1d10ffda2a6639d1a5b2a489564a54c9b2422cda))
+
 ## 0.1.0 (2026-11-08)
 
 

package/runtime/README.md

@@ -72,7 +72,7 @@ cd my-video
 claude
 ```
 
-Run `/mcp` once to authenticate Suno, then `/video-next my-video`. The generated workspace contains the full workflow runtime, so every `npm run cli -- ...` command in this README works inside it. Running `npx coreslopper` without arguments inside a workspace prints the available commands. See [docs/onboarding.md](docs/onboarding.md) for all flags and troubleshooting.
+Run `/mcp` once to authenticate Suno, then `/video-next my-video`. The generated workspace contains the full workflow runtime, so every `npm run cli -- ...` command in this README works inside it. Running `npx coreslopper` without arguments inside a workspace prints the available commands. To move a workspace to a newer release, run `npx coreslopper@latest update` inside it; local edits are kept. See [docs/onboarding.md](docs/onboarding.md) for all flags, updating, and troubleshooting.
 
 ## Quickstarts
 

package/runtime/docs/adr/0010-npx-onboarding.md

@@ -1,6 +1,7 @@
 # npx onboarding with a versioned runtime snapshot
 
 > Extended by [ADR 0011](0011-higgsfield-provider.md): onboarding also checks and stores Higgsfield credentials.
+> Extended by [ADR 0012](0012-workspace-update.md): workspaces are updated with `coreslopper update`, not `init --force`.
 
 **Status:** Accepted
 

package/runtime/docs/adr/0012-workspace-update.md

@@ -0,0 +1,27 @@
+# Update workspaces with a recorded baseline
+
+## Status
+
+Accepted — 2026-11-08
+
+## Context
+
+A workspace is a runtime snapshot, not a git clone (ADR 0010). Until now the only way to pick up a newer workflow was `npx coreslopper@latest init . --force`, which copies the runtime over the workspace. That overwrites every local edit to a skill, command, or config file, and it never deletes a file that upstream removed, so stale skills keep loading in Claude Code.
+
+## Decision
+
+Add `npx coreslopper@latest update [dir]`, a three-way merge between the recorded baseline, the workspace, and the new runtime.
+
+- `init` and `update` store the SHA-256 of every installed runtime file in `coreslopper.workspace.json` (`files`). This is the **baseline**.
+- A file unchanged since the baseline follows upstream: it is updated, or deleted when upstream removed it.
+- A locally changed file is kept. When upstream changed it as well, the new version is written next to it as `<file>.coreslopper-new` for a manual merge; `--force` overwrites instead.
+- `projects/**` is user-owned: missing upstream files are added, but nothing is overwritten or deleted. `.env`, `.mcp.json`, `GETTING_STARTED.md`, and the marker itself are never touched. `package-lock.json` always follows upstream, because `npm install` rewrites it locally.
+- A downgrade is refused unless `--force` is passed. `--dry-run` reports without writing.
+- A workspace created before this ADR has no baseline. Every file that differs from upstream is then a conflict; the user commits and runs `update --force` once, which records the baseline.
+
+## Consequences
+
+- Updating keeps local customizations and removes obsolete workflow files.
+- The marker grows by one hash per runtime file (about 200 entries) and is committed with the workspace.
+- `init --force` remains for repairing a workspace but is no longer the documented update path.
+- There is no line-level merge; a file changed on both sides needs a manual merge of the `.coreslopper-new` copy.

package/runtime/docs/adr/README.md

@@ -15,5 +15,6 @@ Short records of decisions that are hard to reverse, surprising without context,
 | [0009](0009-mit-open-source.md) | MIT open source with explicit third-party notices. |
 | [0010](0010-npx-onboarding.md) | npx onboarding with a versioned runtime snapshot. |
 | [0011](0011-higgsfield-provider.md) | Higgsfield as a second provider; per-project provider selection and role alternatives. |
+| [0012](0012-workspace-update.md) | `coreslopper update` merges a new runtime against a recorded baseline. |
 
 Status values: `Accepted`, `Deprecated`, `Superseded by ADR-NNNN`.

package/runtime/docs/glossary.md

@@ -9,9 +9,13 @@ A self-contained directory created by `npx coreslopper init` that holds the work
 _Avoid_: repo, checkout
 
 **Runtime Snapshot**:
-The versioned copy of the workflow files that `npx coreslopper init` writes into a workspace. It is not a git clone and is updated by re-running init.
+The versioned copy of the workflow files that `npx coreslopper init` writes into a workspace. It is not a git clone and is updated with `npx coreslopper@latest update`, which merges against the **Baseline**.
 _Avoid_: install, template
 
+**Baseline**:
+The SHA-256 of every runtime file as last installed, stored in `coreslopper.workspace.json`. `coreslopper update` compares it with the workspace to tell local edits from untouched workflow files.
+_Avoid_: lockfile, manifest
+
 **Brief**:
 The one-page statement of topic, source, audience, length, formats, and style that anchors every later creative decision.
 _Avoid_: concept, pitch

package/runtime/docs/onboarding.md

@@ -147,15 +147,36 @@ The base install is enough for the motion-only demo and for projects that import
 
 ## Updating a workspace
 
-The workspace is a snapshot. To pick up a newer workflow version, commit your projects first, then merge the runtime in place:
+The workspace is a snapshot. Pick up a newer workflow version with `update`, run from inside the workspace. Commit first, so `git diff` shows exactly what the update changed:
 
 ```bash
-npx coreslopper@latest init . --force --skip-project --no-install
-npm install
-npm run python:sync
+git add -A && git commit -m "chore: before coreslopper update"
+npx coreslopper@latest update --dry-run   # optional: preview
+npx coreslopper@latest update
 ```
 
-This replaces the workflow files (skills, commands, config, packages, scripts, docs) but leaves your project artifacts under `projects/<your-slug>/` and your `.env` untouched. It merges files; workflow files removed upstream are not deleted from the workspace.
+`update` compares three states per file: the **baseline** recorded in `coreslopper.workspace.json` at the last init or update, your workspace, and the new runtime.
+
+| Your file | Upstream | Result |
+|---|---|---|
+| unchanged | changed | updated |
+| unchanged | removed | deleted |
+| changed | unchanged | kept |
+| changed | changed | kept; new version written as `<file>.coreslopper-new` |
+| changed | removed | kept |
+| deleted | any | stays deleted |
+
+Merge each `.coreslopper-new` file into the original and delete it. `--force` overwrites changed files instead.
+
+`projects/` belongs to you: `update` adds new upstream files there but never overwrites or deletes anything. `.env`, `.mcp.json`, and `GETTING_STARTED.md` are never touched. `package-lock.json` always follows upstream. Afterwards `update` runs `npm install` and `uv sync`; pass `--no-install` to skip them.
+
+| Flag | Effect |
+|---|---|
+| `--dry-run` | List the changes without writing anything. |
+| `--force` | Overwrite locally changed files; also allows a downgrade. |
+| `--no-install` | Skip `npm install` and `uv sync`. |
+
+Workspaces created before `update` existed have no baseline, so every file that differs from upstream counts as a conflict. Commit, then run `npx coreslopper@latest update --force` once; it records the baseline for later updates.
 
 ## Troubleshooting
 

package/runtime/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "coreslopper",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "coreslopper",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "license": "MIT",
       "workspaces": [
         "packages/*"

package/runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coreslopper",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": true,
   "type": "module",
   "description": "An open-source, Claude Code-native workflow for producing music videos from brief to render.",

package/runtime/packages/cli/src/init.ts

@@ -5,6 +5,7 @@ import { homedir } from 'node:os';
 import { basename, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
 import { ValidationError } from '@coreslopper/core';
 import { createProject } from './new-project.js';
+import { SKIPPED_DIRECTORIES, hashRuntime } from './update.js';
 import {
   commandExists,
   detectTools,
@@ -59,20 +60,6 @@ export interface InitResult {
   warnings: string[];
 }
 
-const SKIPPED_DIRECTORIES = new Set([
-  '.git',
-  '.cache',
-  '.tools',
-  '.vitest',
-  '.venv',
-  '__pycache__',
-  '.pytest_cache',
-  'node_modules',
-  'dist',
-  'runtime',
-  'tmp',
-]);
-
 export function sanitizeSlug(value: string): string {
   const slug = value
     .toLowerCase()
@@ -188,12 +175,13 @@ function writeFileSyncJson(path: string, value: unknown): void {
   writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
 }
 
-function writeMarker(target: string, projectSlug?: string): void {
+function writeMarker(target: string, files: Record<string, string>, projectSlug?: string): void {
   const marker: WorkspaceMarker = {
     version: 1,
     runtimeVersion: ownVersion(),
     created: new Date().toISOString(),
     ...(projectSlug ? { project: projectSlug } : {}),
+    files,
   };
   writeFileSyncJson(join(target, WORKSPACE_MARKER), marker);
 }
@@ -343,7 +331,7 @@ export async function initWorkspace(options: InitOptions): Promise<InitResult> {
     ? await createFirstProject(target, options.project, warnings)
     : undefined;
 
-  writeMarker(target, projectSlug);
+  writeMarker(target, await hashRuntime(runtime), projectSlug);
 
   let installed = false;
   let uvSynced = false;

package/runtime/packages/cli/src/npx.ts

@@ -9,6 +9,7 @@ import {
 import { createProject } from './new-project.js';
 import { onboard } from './onboarding.js';
 import { printStatus } from './status.js';
+import { printUpdateSummary, updateWorkspace } from './update.js';
 import { formatSeconds, run } from './utils.js';
 import { validateProject } from './validate.js';
 import {
@@ -50,7 +51,7 @@ function workspaceSummary(root: string): void {
   } else {
     console.log('No projects yet. Create one with: npx coreslopper new <slug> --budget 50');
   }
-  console.log('Commands: init, doctor, new, status, validate');
+  console.log('Commands: init, update, doctor, new, status, validate');
 }
 
 const program = new Command();
@@ -96,6 +97,32 @@ program
     }),
   );
 
+program
+  .command('update [dir]')
+  .description('Update the workflow files of a workspace to this coreslopper version; keeps local changes.')
+  .option('--dry-run', 'Show what would change without writing anything')
+  .option('--force', 'Overwrite locally changed files and allow a downgrade')
+  .option('--no-install', 'Skip npm install and uv sync')
+  .option('--runtime <dir>', 'Runtime directory (development only)')
+  .action(
+    (
+      dir: string | undefined,
+      options: { dryRun?: boolean; force?: boolean; install: boolean; runtime?: string },
+    ) =>
+      run(async () => {
+        const target = dir ? resolve(dir) : requireWorkspaceRoot();
+        const result = await updateWorkspace({
+          targetDir: target,
+          runtimeDir: options.runtime,
+          dryRun: options.dryRun,
+          force: options.force,
+          install: options.install,
+          onProgress: (message) => console.log(message),
+        });
+        printUpdateSummary(result);
+      }),
+  );
+
 program
   .command('doctor [dir]')
   .description('Check the workspace, tools, and credentials.')