@venizia/vulcan 0.4.10-14 → 0.4.10-16

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.4.10-14",
3
+ "version": "0.4.10-16",
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-14",
49
- "@venizia/vulcan-okf": "0.4.10-14",
48
+ "@venizia/vulcan-atlas": "0.4.10-16",
49
+ "@venizia/vulcan-okf": "0.4.10-16",
50
50
  "zod": "^4.6.7"
51
51
  },
52
52
  "devDependencies": {
@@ -3,14 +3,38 @@ import type { ICommandContext } from '../common/index.ts';
3
3
  import { runXCommand } from './x.command.ts';
4
4
 
5
5
  const SUBCOMMAND = 'check';
6
+ const NOTES = 'notes';
7
+ const USAGE = `usage: vulcan changelog ${SUBCOMMAND} [--history --base <ref>] | ${NOTES} --version <X.Y.Z> [--migration]`;
6
8
 
7
- /** `vulcan changelog check`: atlas's `changelogs check` run at the pinned version, over this project's entries. */
9
+ /**
10
+ * `vulcan changelog check` and `vulcan changelog notes`: atlas's `changelogs` command run at the pinned version, over this
11
+ * project's entries.
12
+ */
8
13
  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`);
14
+ const rest = opts.args.slice(1);
15
+ const isShape =
16
+ rest.length === 0 || (rest.length === 3 && rest[0] === '--history' && rest[1] === '--base');
17
+
18
+ if (opts.args[0] === NOTES) {
19
+ const isNotes =
20
+ rest[0] === '--version' &&
21
+ rest[1] !== undefined &&
22
+ (rest.length === 2 || (rest.length === 3 && rest[2] === '--migration'));
23
+
24
+ if (!isNotes) {
25
+ process.stderr.write(`${USAGE}\n`);
26
+
27
+ return Promise.resolve(ExitCodes.USAGE);
28
+ }
29
+
30
+ return runXCommand({ ...opts, args: ['atlas', 'changelogs', NOTES, ...rest] });
31
+ }
32
+
33
+ if (opts.args[0] !== SUBCOMMAND || !isShape) {
34
+ process.stderr.write(`${USAGE}\n`);
11
35
 
12
36
  return Promise.resolve(ExitCodes.USAGE);
13
37
  }
14
38
 
15
- return runXCommand({ ...opts, args: ['atlas', 'changelogs', SUBCOMMAND] });
39
+ return runXCommand({ ...opts, args: ['atlas', 'changelogs', SUBCOMMAND, ...rest] });
16
40
  };
@@ -52,7 +52,7 @@ const withApp = (opts: { args: string[]; cwd: string }): string[] => {
52
52
  export const runMigrateCommand = (opts: ICommandContext): Promise<number> => {
53
53
  if (!SUBCOMMANDS.has(opts.args[0] ?? '')) {
54
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',
55
+ 'usage: vulcan migrate plan [--package <name>] [--from <version>] --to <version|latest|next> [--app <dir>] [--format md|json] [--verbose]\n vulcan migrate apply [--package <name>] [--from <version>] --to <version|latest|next> [--app <dir>] [--force]\n',
56
56
  );
57
57
 
58
58
  return Promise.resolve(ExitCodes.USAGE);
@@ -262,15 +262,34 @@ export class CommandTable {
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
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`,
265
+ help: ` changelog check [--history --base <ref>]
266
+ Check the changelog: a version folder changelogs/<X.Y.Z>/{log.md, migration.yaml}
267
+ has a block for every Breaking and Deprecated item; a dated Breaking Change entry
268
+ on or after a date cutover carries one. --history also fails a released folder that
269
+ changed since the base, a stable with no folder, and a dated file, dated after
270
+ knowledge.datedUntil, that was added or edited.
271
+ changelog notes --version <X.Y.Z> [--migration]
272
+ The release notes of a version folder: the body of its log.md, then the packages.
273
+ --migration prints the path of its migration.yaml when that file holds a block,
274
+ and nothing when it does not (what a workflow attaches to the Release)`,
275
+ flags: {
276
+ '--history':
277
+ 'Also run the checks that read git: frozen released folders, stables without a folder, new dated files',
278
+ '--migration':
279
+ 'With notes: print the path of migration.yaml when it holds a block, not the notes',
280
+ },
281
+ values: {
282
+ '--base':
283
+ 'With --history: the commit or branch the change is measured from, e.g. origin/develop',
284
+ '--version': 'With notes: the version folder to read, e.g. 0.4.8',
285
+ },
267
286
  positionals: 1,
268
287
  unknownExit: ExitCodes.USAGE,
269
288
  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.',
289
+ '0 when every entry conforms (notes: printed); 1 when an entry does not, a folder is missing, the tool is missing or the configuration is invalid; 2 for a subcommand other than check or notes.',
271
290
  },
272
291
  [VulcanCommands.MIGRATE]: {
273
- help: ` migrate plan [--package <name>] [--from <version>] --to <version|latest|next> [--app <dir>] [--format md|json]
292
+ help: ` migrate plan [--package <name>] [--from <version>] --to <version|latest|next> [--app <dir>] [--format md|json] [--verbose]
274
293
  What an app must change to move a package between two releases, newer or
275
294
  older: the steps in order, the places in your code they touch (file:line),
276
295
  codemods and data warnings; read only
@@ -288,6 +307,7 @@ export class CommandTable {
288
307
  },
289
308
  flags: {
290
309
  '--force': 'apply: run on an app with uncommitted changes, or outside git',
310
+ '--verbose': 'plan: list every place that imports a module a step is about, not a count',
291
311
  },
292
312
  positionals: 1,
293
313
  unknownExit: ExitCodes.USAGE,
@@ -277,8 +277,25 @@ 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. */
280
+ /**
281
+ * The cutover of the migration gate. `YYYY-MM-DD`: a dated entry on or after it owes a `migration` block when it is a
282
+ * Breaking Change. `X.Y.Z`: version folders from that version on are the changelog and dated files are history.
283
+ */
281
284
  migrationFrom: z
285
+ .string()
286
+ .regex(/^(?:\d{4}-\d{2}-\d{2}|\d+\.\d+\.\d+)$/)
287
+ .optional(),
288
+ /**
289
+ * The command that runs the codemods of this project's migrations: a bare binary name found in the app's
290
+ * `node_modules/.bin`, then fixed words (`['tool', 'codemod']`); default `['devz', 'codemod']`. A migration names
291
+ * a codemod, never a command: the runner is the source project's, so a changelog cannot run anything.
292
+ */
293
+ codemodCommand: z
294
+ .array(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/i))
295
+ .min(1)
296
+ .optional(),
297
+ /** `YYYY-MM-DD`: the last date a dated changelog file may carry; a later one fails the changelog check. */
298
+ datedUntil: z
282
299
  .string()
283
300
  .regex(/^\d{4}-\d{2}-\d{2}$/)
284
301
  .optional(),
@@ -1,7 +1,15 @@
1
1
  import { Glob } from 'bun';
2
2
  import { spawnSync } from 'node:child_process';
3
- import { accessSync, constants, existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
4
- import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
3
+ import {
4
+ accessSync,
5
+ constants,
6
+ existsSync,
7
+ readdirSync,
8
+ readFileSync,
9
+ realpathSync,
10
+ statSync,
11
+ } from 'node:fs';
12
+ import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
5
13
  import { BASE_DIRECTORY, ProjectLayout, RecordValue } from '../common/index.ts';
6
14
  import { LayoutKeys, LayoutFolder } from '../common/layout-folder.ts';
7
15
  import { MCP_SERVER_HINT, ProjectScaffold } from '../init/index.ts';
@@ -26,7 +34,7 @@ import { BrowserSocket, LocalFormat, LocalScan, LocalStates } from '../local/ind
26
34
  import { CLAUDE_LAUNCH_FILE } from '../sync/claude-launch.ts';
27
35
  import { PrivateValues } from './private-values.ts';
28
36
  import { ReplySwitch, OwnerConstants, OwnerReplySwitch, OwnerProfile } from '../owner/index.ts';
29
- import { SkillCatalog } from '@venizia/vulcan-atlas';
37
+ import { SkillCatalog, VersionFolders } from '@venizia/vulcan-atlas';
30
38
  import { HookConstants, ProjectTmp } from '../hooks/index.ts';
31
39
  import { DoctorChecks, DoctorConstants, PrivateValueKinds } from './common/index.ts';
32
40
  import type { IViolation, TDoctorCheck } from './common/index.ts';
@@ -377,6 +385,59 @@ export class ProjectContract {
377
385
  ];
378
386
  }
379
387
 
388
+ /**
389
+ * The changelog folders `changelogs/<X.Y.Z>/` are read by the atlas of VULCAN `CHANGELOG_FOLDERS_FROM` and later;
390
+ * an older one ignores them and answers with no changelog at all. A project that holds a folder with a `log.md`
391
+ * and has an older vulcan installed is told which to install. The version is compared whole: a prerelease of
392
+ * the line before the one that carries the reader still ignores the folders.
393
+ */
394
+ static checkChangelogFolders(opts: ICheckContext): IViolation[] {
395
+ const { changelogs } = opts.config.knowledge;
396
+
397
+ if (changelogs === undefined) {
398
+ return [];
399
+ }
400
+
401
+ const directory = resolve(opts.root, changelogs);
402
+ const hasFolder =
403
+ existsSync(directory) &&
404
+ readdirSync(directory).some(
405
+ (name) => VersionFolders.isName({ name }) && existsSync(join(directory, name, 'log.md')),
406
+ );
407
+ const installedAt = join(opts.root, 'node_modules', '@venizia', 'vulcan');
408
+ const installed = readJsonObject({ file: join(installedAt, 'package.json') })?.['version'];
409
+
410
+ if (!hasFolder || typeof installed !== 'string') {
411
+ return [];
412
+ }
413
+
414
+ // VULCAN's own repository links its workspace package there: that is the source of this project, not an older release.
415
+ try {
416
+ const real = realpathSync(installedAt);
417
+ const fromRoot = relative(realpathSync(opts.root), real);
418
+
419
+ if (
420
+ !isAbsolute(fromRoot) &&
421
+ !fromRoot.startsWith('..') &&
422
+ !fromRoot.split(sep).includes('node_modules')
423
+ ) {
424
+ return [];
425
+ }
426
+ } catch {
427
+ // A link that does not resolve is judged by the version it names.
428
+ }
429
+
430
+ return Bun.semver.order(installed, DoctorConstants.CHANGELOG_FOLDERS_FROM) >= 0
431
+ ? []
432
+ : [
433
+ createViolation({
434
+ check: DoctorChecks.CHANGELOG_FOLDERS,
435
+ file: changelogs,
436
+ message: `holds version folders, but the installed @venizia/vulcan is ${installed}: its atlas ignores them. Install ${DoctorConstants.CHANGELOG_FOLDERS_FROM} or later`,
437
+ }),
438
+ ];
439
+ }
440
+
380
441
  /**
381
442
  * D9: the shared coding style - every lint config builds on it, and the package whose `.configs/`
382
443
  * holds the config declares it, or the root does. A project with no lint config declares it at the
@@ -18,6 +18,8 @@ export class DoctorChecks {
18
18
  static readonly STYLE = 'style';
19
19
  /** The committed .agents/vulcan.manifest.json against the config; a missing or outdated one is an error. */
20
20
  static readonly MANIFEST = 'manifest';
21
+ /** Version folders under the changelog directory while the installed vulcan predates the atlas that reads them; an error. */
22
+ static readonly CHANGELOG_FOLDERS = 'changelog-folders';
21
23
  /** Git tags matching atlas.tagPattern that name no declared package, alias or ignored tag; an error. */
22
24
  static readonly TAGS = 'tags';
23
25
  /** Workspaces declare packages and the knowledge index no longer holds scaffold text; a miss is an error. */
@@ -93,6 +95,8 @@ export class PrivateValueScan {
93
95
  }
94
96
 
95
97
  export class DoctorConstants {
98
+ /** The first VULCAN version whose atlas reads version folders (the first prerelease of the line to carry the reader); an older installed vulcan ignores them. */
99
+ static readonly CHANGELOG_FOLDERS_FROM = '0.4.10-16';
96
100
  static readonly MAKE_INCLUDE_PATTERN =
97
101
  /^-?include\s+\S*@venizia\/vulcan\/base\/make\/vulcan\.mk\s*$/m;
98
102
  /** The `[fmt]` table header of a `bunfig.toml`, on a line of its own, a trailing comment allowed. */
@@ -37,6 +37,7 @@ export class DoctorRunner {
37
37
  ...ProjectContract.checkAdapters(context),
38
38
  ...ProjectContract.checkAgents(context),
39
39
  ...ProjectContract.checkManifest(context),
40
+ ...ProjectContract.checkChangelogFolders(context),
40
41
  ...TagCheck.check(context),
41
42
  ...SkillLint.check(context),
42
43
  ...ProjectContract.checkStyle(context),
@@ -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, migrationFrom } = config.knowledge;
215
+ const { wiki, changelogs, migrationFrom, datedUntil, codemodCommand } = config.knowledge;
216
216
 
217
217
  const manifest = {
218
218
  [ManifestConstants.GENERATED_KEY]: ManifestConstants.GENERATED_NOTE,
@@ -235,6 +235,8 @@ export class ProjectManifest {
235
235
  ...(wiki === undefined ? {} : { wiki }),
236
236
  ...(changelogs === undefined ? {} : { changelogs }),
237
237
  migrationFrom,
238
+ ...(datedUntil === undefined ? {} : { datedUntil }),
239
+ ...(codemodCommand === undefined ? {} : { codemodCommand }),
238
240
  },
239
241
  release: {
240
242
  tagPattern: config.atlas.tagPattern,