@venizia/vulcan 0.4.10-11 → 0.4.10-13

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
@@ -33,6 +33,9 @@ flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
33
33
  | `profile [show\|edit\|reset]` | Tell VULCAN how you like to work (reply language, tone, habits) in `.agents/local/profile.json` |
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
+ | `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` |
36
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 |
37
40
  | `help`, `version` | `help` prints the usage; `version` prints the installed version |
38
41
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.4.10-11",
3
+ "version": "0.4.10-13",
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-11",
49
- "@venizia/vulcan-okf": "0.4.10-11",
48
+ "@venizia/vulcan-atlas": "0.4.10-13",
49
+ "@venizia/vulcan-okf": "0.4.10-13",
50
50
  "zod": "^4.6.7"
51
51
  },
52
52
  "devDependencies": {
@@ -0,0 +1,16 @@
1
+ import { ExitCodes } from '../common/index.ts';
2
+ import type { ICommandContext } from '../common/index.ts';
3
+ import { runXCommand } from './x.command.ts';
4
+
5
+ const SUBCOMMAND = 'check';
6
+
7
+ /** `vulcan changelog check`: atlas's `changelogs check` run at the pinned version, over this project's entries. */
8
+ export const runChangelogCommand = (opts: ICommandContext): Promise<number> => {
9
+ if (opts.args[0] !== SUBCOMMAND || opts.args.length > 1) {
10
+ process.stderr.write(`usage: vulcan changelog ${SUBCOMMAND}\n`);
11
+
12
+ return Promise.resolve(ExitCodes.USAGE);
13
+ }
14
+
15
+ return runXCommand({ ...opts, args: ['atlas', 'changelogs', SUBCOMMAND] });
16
+ };
@@ -8,6 +8,10 @@ export const COMMAND_LOADERS: Record<string, () => Promise<TCommandHandler>> = {
8
8
  import('./agents.command.ts').then((module) => module.runAgentsCommand),
9
9
  [VulcanCommands.BOARD]: () =>
10
10
  import('./board.command.ts').then((module) => module.runBoardCommand),
11
+ [VulcanCommands.CHANGELOG]: () =>
12
+ import('./changelog.command.ts').then((module) => module.runChangelogCommand),
13
+ [VulcanCommands.MIGRATE]: () =>
14
+ import('./migrate.command.ts').then((module) => module.runMigrateCommand),
11
15
  [VulcanCommands.CLEAN]: () =>
12
16
  import('./clean.command.ts').then((module) => module.runCleanCommand),
13
17
  [VulcanCommands.COMMIT_CHECK]: () =>
@@ -0,0 +1,18 @@
1
+ import { ExitCodes } from '../common/index.ts';
2
+ import type { ICommandContext } from '../common/index.ts';
3
+ import { runXCommand } from './x.command.ts';
4
+
5
+ const SUBCOMMANDS = new Set(['plan', 'apply']);
6
+
7
+ /** `vulcan migrate plan|apply`: atlas's `migrate` run at the pinned version, over the sources this project serves. */
8
+ export const runMigrateCommand = (opts: ICommandContext): Promise<number> => {
9
+ if (!SUBCOMMANDS.has(opts.args[0] ?? '')) {
10
+ process.stderr.write(
11
+ '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',
12
+ );
13
+
14
+ return Promise.resolve(ExitCodes.USAGE);
15
+ }
16
+
17
+ return runXCommand({ ...opts, args: ['atlas', 'migrate', ...opts.args] });
18
+ };
@@ -261,6 +261,39 @@ export class CommandTable {
261
261
  exits:
262
262
  '0 on success; 1 when --stable and --nightly are both given, the dist-tags cannot be read, or the install or sync fails.',
263
263
  },
264
+ [VulcanCommands.CHANGELOG]: {
265
+ help: ` changelog check Check the changelog entries' \`migration\` blocks: a Breaking Change entry
266
+ dated on or after knowledge.migrationFrom must carry one, and every block must be valid`,
267
+ positionals: 1,
268
+ unknownExit: ExitCodes.USAGE,
269
+ exits:
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
+ },
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
+ },
264
297
  [VulcanCommands.X]: {
265
298
  help: ` x <tool> [args...] Run a shipped tool at the pinned version: okf, atlas`,
266
299
  passthrough: true,
@@ -15,6 +15,8 @@ export class VulcanCommands {
15
15
  static readonly COMMIT_CHECK = 'commit-check';
16
16
  static readonly BOARD = 'board';
17
17
  static readonly EVENT = 'event';
18
+ static readonly CHANGELOG = 'changelog';
19
+ static readonly MIGRATE = 'migrate';
18
20
  static readonly X = 'x';
19
21
  static readonly HELP = 'help';
20
22
  static readonly VERSION = 'version';
@@ -277,6 +277,11 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
277
277
  wiki: z.string().optional(),
278
278
  /** Folder of the changelog files; absent means the project has none. */
279
279
  changelogs: z.string().optional(),
280
+ /** `YYYY-MM-DD`: an entry dated on or after it owes a `migration` block when it is a Breaking Change; earlier entries are never checked. */
281
+ migrationFrom: z
282
+ .string()
283
+ .regex(/^\d{4}-\d{2}-\d{2}$/)
284
+ .optional(),
280
285
  /** A map of code areas to concepts; no shipped skill reads it. */
281
286
  })
282
287
  .default({ bundle: ConfigConstants.DEFAULT_KNOWLEDGE_BUNDLE }),
@@ -212,7 +212,7 @@ export class ProjectManifest {
212
212
  */
213
213
  static render(opts: { root: string; config: TResolvedConfig }): string {
214
214
  const { config } = opts;
215
- const { wiki, changelogs } = config.knowledge;
215
+ const { wiki, changelogs, migrationFrom } = config.knowledge;
216
216
 
217
217
  const manifest = {
218
218
  [ManifestConstants.GENERATED_KEY]: ManifestConstants.GENERATED_NOTE,
@@ -234,6 +234,7 @@ export class ProjectManifest {
234
234
  bundle: config.knowledge.bundle,
235
235
  ...(wiki === undefined ? {} : { wiki }),
236
236
  ...(changelogs === undefined ? {} : { changelogs }),
237
+ migrationFrom,
237
238
  },
238
239
  release: {
239
240
  tagPattern: config.atlas.tagPattern,