@venizia/vulcan 0.4.10-12 → 0.4.10-14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -34,6 +34,8 @@ flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
34
34
  | `clean [--tmp\|--worktrees\|--clones\|--cache\|--all] [--include-fresh] [--yes]` | List what an agent left under `.agents/local/` (a dry run) and, with `--yes`, remove it |
35
35
  | `upgrade [--stable \| --nightly] [<version\|tag>]` | Install the target `@venizia/vulcan`, then run `sync` from the newly installed CLI. `--stable` (default) is the `latest` dist-tag, never a prerelease; `--nightly` is the higher of `latest` and `next`; a named version or tag wins over both. `--nightly` that cannot read the dist-tags exits 1; a stable upgrade from an installed prerelease says that `--nightly` keeps the prerelease line |
36
36
  | `changelog check` | Check the changelog entries' `migration` blocks: a Breaking Change entry dated on or after `knowledge.migrationFrom` must carry one, and every block must be valid |
37
+ | `migrate plan --to <version>` | What an app must change to move a package between two releases, newer or older: the steps in order, where its code touches them, codemods and data warnings; read only |
38
+ | `migrate apply --to <version>` | Run the codemods the plan links (`--reverse` for a rollback) and print the steps that stay manual; refuses an app with uncommitted changes unless `--force` |
37
39
  | `x <tool> [args...]` | Run a shipped tool at the pinned version: `okf`, `atlas`. `x --help` prints the help; `x <tool> --help` goes to the tool |
38
40
  | `help`, `version` | `help` prints the usage; `version` prints the installed version |
39
41
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.4.10-12",
3
+ "version": "0.4.10-14",
4
4
  "description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
5
5
  "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
6
6
  "bugs": {
@@ -45,8 +45,8 @@
45
45
  },
46
46
  "dependencies": {
47
47
  "@clack/prompts": "1.8.1",
48
- "@venizia/vulcan-atlas": "0.4.10-12",
49
- "@venizia/vulcan-okf": "0.4.10-12",
48
+ "@venizia/vulcan-atlas": "0.4.10-14",
49
+ "@venizia/vulcan-okf": "0.4.10-14",
50
50
  "zod": "^4.6.7"
51
51
  },
52
52
  "devDependencies": {
@@ -10,6 +10,8 @@ export const COMMAND_LOADERS: Record<string, () => Promise<TCommandHandler>> = {
10
10
  import('./board.command.ts').then((module) => module.runBoardCommand),
11
11
  [VulcanCommands.CHANGELOG]: () =>
12
12
  import('./changelog.command.ts').then((module) => module.runChangelogCommand),
13
+ [VulcanCommands.MIGRATE]: () =>
14
+ import('./migrate.command.ts').then((module) => module.runMigrateCommand),
13
15
  [VulcanCommands.CLEAN]: () =>
14
16
  import('./clean.command.ts').then((module) => module.runCleanCommand),
15
17
  [VulcanCommands.COMMIT_CHECK]: () =>
@@ -0,0 +1,71 @@
1
+ import { existsSync } from 'node:fs';
2
+ import { dirname, join, resolve } from 'node:path';
3
+ import { ExitCodes } from '../common/index.ts';
4
+ import type { ICommandContext } from '../common/index.ts';
5
+ import { ConfigLoader } from '../config/index.ts';
6
+ import { runXCommand } from './x.command.ts';
7
+
8
+ const SUBCOMMANDS = new Set(['plan', 'apply']);
9
+
10
+ /**
11
+ * The project a folder belongs to: the nearest folder at or above `cwd` that has a VULCAN config, never
12
+ * above the git work tree root (a config of an unrelated parent is not this project's). `undefined` when
13
+ * there is none, so the folder is served as it is and atlas says there is nothing to serve.
14
+ */
15
+ const enclosingProjectOf = (opts: { cwd: string }): string | undefined => {
16
+ let directory = opts.cwd;
17
+
18
+ for (;;) {
19
+ if (ConfigLoader.findFile({ root: directory }) !== undefined) {
20
+ return directory;
21
+ }
22
+
23
+ const parent = dirname(directory);
24
+
25
+ if (existsSync(join(directory, '.git')) || parent === directory) {
26
+ return undefined;
27
+ }
28
+
29
+ directory = parent;
30
+ }
31
+ };
32
+
33
+ /** `--app` made absolute against the folder the command was run in, and added (as that folder) when absent. */
34
+ const withApp = (opts: { args: string[]; cwd: string }): string[] => {
35
+ const args = [...opts.args];
36
+ const at = args.findIndex((arg) => arg === '--app' || arg.startsWith('--app='));
37
+
38
+ if (at === -1) {
39
+ return [...args, '--app', opts.cwd];
40
+ }
41
+
42
+ if (args[at] === '--app') {
43
+ args[at + 1] = resolve(opts.cwd, args[at + 1] ?? '');
44
+ } else {
45
+ args[at] = `--app=${resolve(opts.cwd, args[at].slice('--app='.length))}`;
46
+ }
47
+
48
+ return args;
49
+ };
50
+
51
+ /** `vulcan migrate plan|apply`: atlas's `migrate` run at the pinned version, over the sources this project serves. */
52
+ export const runMigrateCommand = (opts: ICommandContext): Promise<number> => {
53
+ if (!SUBCOMMANDS.has(opts.args[0] ?? '')) {
54
+ process.stderr.write(
55
+ 'usage: vulcan migrate plan [--package <name>] [--from <version>] --to <version|latest|next> [--app <dir>] [--format md|json]\n vulcan migrate apply [--package <name>] [--from <version>] --to <version|latest|next> [--app <dir>] [--force]\n',
56
+ );
57
+
58
+ return Promise.resolve(ExitCodes.USAGE);
59
+ }
60
+
61
+ const project = enclosingProjectOf({ cwd: opts.cwd });
62
+
63
+ // Run in the project that has the config; the app is the folder the command was run in unless `--app` says otherwise.
64
+ return project === undefined || project === opts.cwd
65
+ ? runXCommand({ ...opts, args: ['atlas', 'migrate', ...opts.args] })
66
+ : runXCommand({
67
+ ...opts,
68
+ cwd: project,
69
+ args: ['atlas', 'migrate', ...withApp({ args: opts.args, cwd: opts.cwd })],
70
+ });
71
+ };
@@ -269,6 +269,31 @@ export class CommandTable {
269
269
  exits:
270
270
  '0 when every entry conforms; 1 when an entry does not, the tool is missing or the configuration is invalid; 2 for a subcommand other than check.',
271
271
  },
272
+ [VulcanCommands.MIGRATE]: {
273
+ help: ` migrate plan [--package <name>] [--from <version>] --to <version|latest|next> [--app <dir>] [--format md|json]
274
+ What an app must change to move a package between two releases, newer or
275
+ older: the steps in order, the places in your code they touch (file:line),
276
+ codemods and data warnings; read only
277
+ migrate apply [--package <name>] [--from <version>] --to <version|latest|next> [--app <dir>] [--force]
278
+ Run the codemods the plan links, once each in order (reversed for a
279
+ rollback), then print the steps that stay manual; refuses an app with
280
+ uncommitted changes or outside git unless --force`,
281
+ values: {
282
+ '--package': 'The package to move; absent, every installed package the sources know',
283
+ '--from': 'The version the app runs now; default the installed one',
284
+ '--to':
285
+ 'A version, latest (newest stable) or next (newest release) of the atlas release table',
286
+ '--app': 'The app directory to scan; default the current directory',
287
+ '--format': 'md (default) or json (plan only)',
288
+ },
289
+ flags: {
290
+ '--force': 'apply: run on an app with uncommitted changes, or outside git',
291
+ },
292
+ positionals: 1,
293
+ unknownExit: ExitCodes.USAGE,
294
+ exits:
295
+ '0 when a plan is printed or apply ran; 1 when the plan cannot be made (an unknown package or version, nothing installed), apply is refused (uncommitted changes, no git, no devz) or a codemod fails, or the tool is missing; 2 for a subcommand other than plan or apply, or a missing --to.',
296
+ },
272
297
  [VulcanCommands.X]: {
273
298
  help: ` x <tool> [args...] Run a shipped tool at the pinned version: okf, atlas`,
274
299
  passthrough: true,
@@ -16,6 +16,7 @@ export class VulcanCommands {
16
16
  static readonly BOARD = 'board';
17
17
  static readonly EVENT = 'event';
18
18
  static readonly CHANGELOG = 'changelog';
19
+ static readonly MIGRATE = 'migrate';
19
20
  static readonly X = 'x';
20
21
  static readonly HELP = 'help';
21
22
  static readonly VERSION = 'version';