@venizia/vulcan 0.4.10-15 → 0.4.10-17

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-15",
3
+ "version": "0.4.10-17",
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-15",
49
- "@venizia/vulcan-okf": "0.4.10-15",
48
+ "@venizia/vulcan-atlas": "0.4.10-17",
49
+ "@venizia/vulcan-okf": "0.4.10-17",
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
  };
@@ -262,12 +262,31 @@ 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
292
  help: ` migrate plan [--package <name>] [--from <version>] --to <version|latest|next> [--app <dir>] [--format md|json] [--verbose]
@@ -1,4 +1,5 @@
1
1
  import { z } from 'zod';
2
+ import { SiteUrl } from '@venizia/vulcan-atlas';
2
3
  import { LayoutFolder } from '../common/layout-folder.ts';
3
4
  import { DOCTOR_SCHEMA } from '../doctor/schema.ts';
4
5
  import { GuardDecisions } from '../hooks/common/constants.ts';
@@ -277,11 +278,48 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
277
278
  wiki: z.string().optional(),
278
279
  /** Folder of the changelog files; absent means the project has none. */
279
280
  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
+ /**
282
+ * The cutover of the migration gate. `YYYY-MM-DD`: a dated entry on or after it owes a `migration` block when it is a
283
+ * Breaking Change. `X.Y.Z`: version folders from that version on are the changelog and dated files are history.
284
+ */
281
285
  migrationFrom: z
286
+ .string()
287
+ .regex(/^(?:\d{4}-\d{2}-\d{2}|\d+\.\d+\.\d+)$/)
288
+ .optional(),
289
+ /**
290
+ * The command that runs the codemods of this project's migrations: a bare binary name found in the app's
291
+ * `node_modules/.bin`, then fixed words (`['tool', 'codemod']`); default `['devz', 'codemod']`. A migration names
292
+ * a codemod, never a command: the runner is the source project's, so a changelog cannot run anything.
293
+ */
294
+ codemodCommand: z
295
+ .array(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/i))
296
+ .min(1)
297
+ .optional(),
298
+ /** `YYYY-MM-DD`: the last date a dated changelog file may carry; a later one fails the changelog check. */
299
+ datedUntil: z
282
300
  .string()
283
301
  .regex(/^\d{4}-\d{2}-\d{2}$/)
284
302
  .optional(),
303
+ /**
304
+ * The address of the project's wiki (`https://wiki.example.com`): `vulcan migrate plan` prints a link to the
305
+ * upgrade guide of each step on it, `<siteUrl>/changelogs/<version>/upgrade#<id>`. An https address (http only on
306
+ * localhost) with no credentials, query, fragment or control character, kept without its trailing slash; omit it
307
+ * and the plan prints no link.
308
+ */
309
+ siteUrl: z
310
+ .string()
311
+ .transform((value, context) => {
312
+ const parsed = SiteUrl.parse({ value });
313
+
314
+ if ('problem' in parsed) {
315
+ context.addIssue({ code: 'custom', message: parsed.problem });
316
+
317
+ return z.NEVER;
318
+ }
319
+
320
+ return parsed.href;
321
+ })
322
+ .optional(),
285
323
  /** A map of code areas to concepts; no shipped skill reads it. */
286
324
  })
287
325
  .default({ bundle: ConfigConstants.DEFAULT_KNOWLEDGE_BUNDLE }),
@@ -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,8 @@ 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, siteUrl, codemodCommand } =
216
+ config.knowledge;
216
217
 
217
218
  const manifest = {
218
219
  [ManifestConstants.GENERATED_KEY]: ManifestConstants.GENERATED_NOTE,
@@ -235,6 +236,9 @@ export class ProjectManifest {
235
236
  ...(wiki === undefined ? {} : { wiki }),
236
237
  ...(changelogs === undefined ? {} : { changelogs }),
237
238
  migrationFrom,
239
+ ...(datedUntil === undefined ? {} : { datedUntil }),
240
+ ...(siteUrl === undefined ? {} : { siteUrl }),
241
+ ...(codemodCommand === undefined ? {} : { codemodCommand }),
238
242
  },
239
243
  release: {
240
244
  tagPattern: config.atlas.tagPattern,