@bitakit/cli 0.2.7 → 0.2.8

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/AGENTS.md CHANGED
@@ -35,3 +35,18 @@ contracts and checks there and update them with the code; shared rules stay in t
35
35
  - `bitakit migrate` is the 0.1 upgrade; do not run it to tidy a current project.
36
36
  - Install printed Playwright or test dependencies only within the user's authorized scope;
37
37
  obtain missing approval without requesting an authorization already given again.
38
+
39
+ ## Passive package inspection
40
+
41
+ Info and Doctor read package metadata and static IDs without executing package entries or
42
+ discovery hooks. Info JSON adds provenance, package identity, parent, descriptive metadata and
43
+ membership to the version-1 inventory. Optional metadata problems warn; contradictory static
44
+ IDs in selected copies and conflicting startup IDs are errors. Physical copies remain visible;
45
+ unselected copies have `enabled: false` and Doctor reports their selection separately. `bitakit build` adds `pluginId` to its version-1
46
+ sidecar, accepts historical nonempty runtime IDs (including numeric-leading IDs), and retains
47
+ its npm-name fallback in `metadata.name`. New display titles use `bitakit.title`. Metadata
48
+ warnings identify their actual sources; ignored-file warnings stay in the contribution check.
49
+ Info text includes runtime plugin IDs and labels unselected physical copies separately from
50
+ disabled plugins. JSON includes `selected` and `diagnostics.identityConflicts`; Info and Doctor
51
+ use the same passive startup collision evidence. Unknown package versions are never printed
52
+ as JavaScript undefined. Inventory record keys can change when packages are hoisted differently.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bitakit/cli",
3
- "version": "0.2.7",
3
+ "version": "0.2.8",
4
4
  "description": "BitaKit project commands: add plugins and contributions, check a project with doctor.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -25,8 +25,8 @@
25
25
  "test": "node --test tests/*.test.mjs"
26
26
  },
27
27
  "dependencies": {
28
- "@bitakit/core": "^0.2.6",
29
- "@bitakit/discovery": "^0.2.4",
28
+ "@bitakit/core": "^0.2.8",
29
+ "@bitakit/discovery": "^0.2.5",
30
30
  "commander": "15.0.0",
31
31
  "typescript": "^5.9.3"
32
32
  },
@@ -185,3 +185,13 @@ Say which plugin owns the page (`src/plugins/about`), that its URL comes from th
185
185
  `ui/pages/index.tsx` (`/about`), and that the sidebar entry is the Action `about.open` placed in
186
186
  Shell's `shell.navigation` slot. To try it: start the dev server, click "About" in the navigation (the
187
187
  sidebar, or the top bar in Shell's navbar layout) or open `/about`.
188
+
189
+ ## Plugin metadata and grouping
190
+
191
+ Local titles, descriptions and tags belong in `plugin.config.ts` → `metadata`. Their application
192
+ membership is derived. For package plugins use standard package.json fields and `bitakit.title`,
193
+ `tags`, `coverImage`, `memberOf`; old tags/images remain fallbacks. `memberOf: ['*']` means general
194
+ purpose; absence means unspecified. Host `bitakit.config.ts` may declare `bundles: [{ id, label? }]`.
195
+ Package and bundle names compare lowercase with scopes preserved; runtime IDs do not change.
196
+ `bitakit info --json` shows provenance and membership without running package entries or hooks.
197
+ Keep static `bitakit.id` consistent with the built sidecar; grouping never adds dependencies.
package/src/build.mjs CHANGED
@@ -3,6 +3,7 @@ import { cp, mkdir, realpath, rm, writeFile } from 'node:fs/promises';
3
3
  import { createRequire } from 'node:module';
4
4
  import path from 'node:path';
5
5
  import { describeModule, describeDefinitions, validatePackageStyles } from '@bitakit/discovery';
6
+ import { packageMetadataSources, projectPluginMetadataSources } from '@bitakit/core';
6
7
  import { findProject } from './project.mjs';
7
8
 
8
9
  const quote = JSON.stringify;
@@ -78,6 +79,7 @@ export async function buildPlugin({ cwd, check = false } = {}) {
78
79
  JSON.stringify(
79
80
  {
80
81
  version: 1,
82
+ pluginId: id,
81
83
  definitions: slotInfo.definitions.map((item) => ({
82
84
  ...item,
83
85
  file: source(item.file),
@@ -174,19 +176,20 @@ function entry(id, module, manifest, metadata, local) {
174
176
  const name = load(item.file);
175
177
  return `discoveredFile(${name}, ${quote(item.path)}, ${quote(path.relative(module.directory, item.file).split(path.sep).join('/'))})`;
176
178
  });
177
- const info = {};
178
- for (const key of [
179
- 'name',
180
- 'version',
181
- 'description',
182
- 'author',
183
- 'homepage',
184
- 'bugs',
185
- 'license',
186
- 'coverImage',
187
- 'tags',
188
- ])
189
- if (manifest[key] !== undefined) info[key] = manifest[key];
179
+ const sources = packageMetadataSources(manifest);
180
+ const { metadata: info, warnings } = projectPluginMetadataSources([
181
+ ...Object.entries(sources.canonical).map(([key, value]) => ({
182
+ value: { [key]: value },
183
+ location: `package.json ${['title', 'tags', 'coverImage'].includes(key) ? `${manifest.bitakit ? 'bitakit' : 'foundation'}.` : ''}${key}`,
184
+ })),
185
+ ...Object.entries(sources.legacy).map(([key, value]) => ({
186
+ value: { [key]: value },
187
+ location: `package.json ${key}`,
188
+ })),
189
+ ]);
190
+ // Preserve the historical public name fallback; full package identity is recorded separately.
191
+ if (info.name === undefined && typeof manifest.name === 'string') info.name = manifest.name;
192
+ for (const warning of warnings) console.warn(`[bitakit] package.json: ${warning}`);
190
193
  const services = discovered(module.services);
191
194
  const settings = discovered(module.settings);
192
195
  const settingsPage = module.settingsPage
package/src/cli.mjs CHANGED
@@ -303,7 +303,7 @@ program
303
303
  .action(async (options) => {
304
304
  const project = await findProject();
305
305
  if (project.kind !== 'app') throw new Error('Run "bitakit info" inside an app.');
306
- const description = await describeBitaKit(project.root);
306
+ const description = await describeBitaKit(project.root, { packageMetadataOnly: true });
307
307
  const inventory = await inspectionFromDescription(description);
308
308
  if (options.json) {
309
309
  console.log(JSON.stringify(inventory, null, 2));
@@ -313,8 +313,19 @@ program
313
313
  const title =
314
314
  plugin.source.kind === 'package' ? `Package "${plugin.id}"` : `Plugin "${plugin.id}"`;
315
315
  console.log(
316
- `\n${styleText('bold', title)}${plugin.enabled === false ? ' (disabled)' : ''} ${styleText('dim', plugin.source.path ?? '')}`,
316
+ `\n${styleText('bold', title)}${plugin.selected === false ? ' (not selected)' : plugin.enabled === false ? ' (disabled)' : ''} ${styleText('dim', plugin.source.path ?? '')}`,
317
317
  );
318
+ console.log(` origin: ${plugin.origin ?? 'unknown'}`);
319
+ console.log(` plugin ID: ${plugin.pluginId ?? 'unavailable'}`);
320
+ if (plugin.package)
321
+ console.log(
322
+ ` package: ${plugin.package.name}${plugin.package.version ? `@${plugin.package.version}` : ''}`,
323
+ );
324
+ if (plugin.parent) console.log(` parent: ${plugin.parent}`);
325
+ if (plugin.membership)
326
+ console.log(
327
+ ` membership: ${plugin.membership.state}${plugin.membership.bundles.length ? ` (${plugin.membership.bundles.map((entry) => `${entry.id}${entry.resolved ? '' : ' [unresolved]'}`).join(', ')})` : ''}`,
328
+ );
318
329
  if (plugin.declarations === null)
319
330
  console.log(' declarations: unavailable (static package entry)');
320
331
  else
@@ -326,6 +337,10 @@ program
326
337
  .join(', ')}`,
327
338
  );
328
339
  }
340
+ if (inventory.diagnostics.identityConflicts.length)
341
+ console.log(`\n${styleText('yellow', 'Static plugin ID conflicts:')}`);
342
+ for (const conflict of inventory.diagnostics.identityConflicts)
343
+ console.log(` ${styleText('yellow', conflict)}`);
329
344
  console.log('\nLive state: unavailable (static discovery).');
330
345
  if (description.warnings.length) {
331
346
  console.log(
package/src/doctor.mjs CHANGED
@@ -12,6 +12,7 @@ import { checkAgentFiles } from './doctor-agent-files.mjs';
12
12
  import { exists, findProject } from './project.mjs';
13
13
  import { appRoutes, catchAllRoute, rootLayouts, shellGroup } from './routes.mjs';
14
14
  import { describeSlots } from './slots.mjs';
15
+ import { identityConflictsFromDescription } from './inventory.mjs';
15
16
 
16
17
  /**
17
18
  * Checks a project for the problems that most often break a BitaKit app: mixed package
@@ -60,11 +61,35 @@ export async function doctor({ cwd } = {}) {
60
61
  }
61
62
  let description;
62
63
  try {
63
- description = await describeBitaKit(project.root);
64
+ description = await describeBitaKit(project.root, {
65
+ packageMetadataOnly: true,
66
+ auditPackageStyles: true,
67
+ });
64
68
  } catch (error) {
65
69
  results.push({ status: 'error', title: 'Discovery failed', details: [error.message] });
66
70
  return { project, results };
67
71
  }
72
+ const identityConflicts = identityConflictsFromDescription(description);
73
+ if (identityConflicts.length)
74
+ results.push({
75
+ status: 'error',
76
+ title: 'Conflicting static plugin IDs',
77
+ details: identityConflicts,
78
+ });
79
+ const metadataWarnings = description.metadataWarnings ?? [];
80
+ if (metadataWarnings.length)
81
+ results.push({
82
+ status: 'warn',
83
+ title: 'Plugin metadata',
84
+ details: [...new Set(metadataWarnings)],
85
+ fix: 'Correct the optional declaration at its source. Local membership is derived; folder declarations retain precedence over package fallbacks.',
86
+ });
87
+ if (description.packageWarnings?.length)
88
+ results.push({
89
+ status: 'warn',
90
+ title: 'Installed package copies',
91
+ details: description.packageWarnings,
92
+ });
68
93
  results.push(...(await checkWiring(project)));
69
94
  const modules = [
70
95
  { ...description.app, isApp: true },
@@ -844,11 +869,17 @@ async function checkStyles(project, description) {
844
869
  fix: `Add this line after @import 'tailwindcss'; in ${target}:\n\n@import '${relative.split(path.sep).join('/')}';`,
845
870
  };
846
871
  }
847
- /** Discovery warnings are either deprecations that migrate fixes, or files it skips. */
872
+ /** Metadata/package categories come from their producers, never filenames in warning text. */
848
873
  const isDeprecation = (warning) => warning.includes('bitakit migrate');
849
874
  const plural = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
850
875
  function checkIgnored(description) {
851
- const ignored = description.warnings.filter((warning) => !isDeprecation(warning));
876
+ const classified = new Set([
877
+ ...(description.metadataWarnings ?? []),
878
+ ...(description.packageWarnings ?? []),
879
+ ]);
880
+ const ignored = description.warnings.filter(
881
+ (warning) => !isDeprecation(warning) && !classified.has(warning),
882
+ );
852
883
  if (!ignored.length)
853
884
  return { status: 'ok', title: 'Every contribution file has a default export' };
854
885
  return {
package/src/inventory.mjs CHANGED
@@ -1,8 +1,32 @@
1
1
  import { readFile } from 'node:fs/promises';
2
2
  import path from 'node:path';
3
3
  import ts from 'typescript';
4
- import { createInventory } from '@bitakit/core';
5
- import { describeDefinitions } from '@bitakit/discovery';
4
+ import {
5
+ createInventory,
6
+ pluginMembership,
7
+ inventoryMetadata,
8
+ projectPluginMetadata,
9
+ } from '@bitakit/core';
10
+ import { describeDefinitions, pluginIdentityConflicts } from '@bitakit/discovery';
11
+
12
+ /** The same authoritative startup-ID evidence for passive info and doctor; never imports code. */
13
+ export function identityConflictsFromDescription(description) {
14
+ return pluginIdentityConflicts([
15
+ { id: description.app.id, source: 'application' },
16
+ ...description.plugins
17
+ .filter((plugin) => plugin.enabled)
18
+ .map((plugin) => ({ id: plugin.id, source: plugin.directory })),
19
+ ...Object.entries(description.packagePlugins ?? {})
20
+ .filter(
21
+ ([entry, record]) =>
22
+ record.selected !== false && !description.catalogPackages?.includes(entry),
23
+ )
24
+ .map(([entry, record]) => ({
25
+ id: record.pluginId,
26
+ source: `${record.name}@${record.version ?? '?'} (${entry})`,
27
+ })),
28
+ ]);
29
+ }
6
30
 
7
31
  const kinds = {
8
32
  services: 'service',
@@ -105,22 +129,56 @@ export async function inspectionFromDescription(description) {
105
129
  plugins.push({
106
130
  id: module.id,
107
131
  pluginId: module.id,
132
+ application: app,
133
+ origin: module.origin?.kind ?? 'unknown',
134
+ parent: module.parent ?? null,
135
+ package: module.origin?.package ?? null,
136
+ declaredMembership: module.origin?.memberOf ?? null,
137
+ membership: pluginMembership(module.origin, {
138
+ application: app,
139
+ bundle: description.bundle,
140
+ knownBundles: description.knownBundles,
141
+ }),
108
142
  enabled: module.enabled ?? true,
143
+ selected: null,
109
144
  source: { kind: 'file', path: module.directory },
110
- metadata: {},
145
+ metadata: inventoryMetadata(module.metadata),
111
146
  dependencies: module.dependencies ?? [],
112
147
  declarations,
113
148
  });
114
149
  }
115
- for (const specifier of description.packages)
150
+ for (const specifier of description.packages) {
151
+ const record = description.packagePlugins?.[specifier];
116
152
  plugins.push({
117
153
  id: specifier,
118
- pluginId: null,
119
- enabled: description.catalogPackages?.includes(specifier) ? null : true,
154
+ pluginId: record?.pluginId ?? null,
155
+ application: false,
156
+ selected: record?.selected ?? null,
157
+ origin: record?.origin?.kind ?? 'unknown',
158
+ parent: null,
159
+ package: record?.origin?.package ?? null,
160
+ declaredMembership: record?.origin?.memberOf ?? null,
161
+ membership: pluginMembership(record?.origin, {
162
+ bundle: description.bundle,
163
+ knownBundles: description.knownBundles,
164
+ }),
165
+ enabled:
166
+ record?.selected === false
167
+ ? false
168
+ : description.catalogPackages?.includes(specifier)
169
+ ? null
170
+ : true,
120
171
  source: { kind: 'package', path: specifier },
121
- metadata: {},
172
+ metadata: inventoryMetadata(
173
+ projectPluginMetadata(record?.origin.metadata?.canonical, record?.origin.metadata?.legacy)
174
+ .metadata,
175
+ ),
122
176
  dependencies: null,
123
177
  declarations: null,
124
178
  });
125
- return createInventory(plugins);
179
+ }
180
+ return {
181
+ ...createInventory(plugins),
182
+ diagnostics: { identityConflicts: identityConflictsFromDescription(description) },
183
+ };
126
184
  }
package/src/project.mjs CHANGED
@@ -1,6 +1,7 @@
1
1
  import { access, readFile } from 'node:fs/promises';
2
2
  import path from 'node:path';
3
- import { loadDiscoveryConfig } from '@bitakit/discovery';
3
+ import { loadDiscoveryConfig, packagePluginId } from '@bitakit/discovery';
4
+ export { packagePluginId } from '@bitakit/discovery';
4
5
 
5
6
  /** The nearest package.json above `cwd`: the project root and its manifest, without reading any configuration. */
6
7
  export async function findProjectRoot(cwd = process.cwd()) {
@@ -81,17 +82,6 @@ async function describeProject(root, manifest) {
81
82
  };
82
83
  }
83
84
 
84
- /** `@acme/bitakit-notes` → `notes`; the package manifest may set `bitakit.id` explicitly. */
85
- export function packagePluginId(name = '') {
86
- return (
87
- name
88
- .replace(/^@[^/]+\//, '')
89
- .replace(/^bitakit-(plugin-)?/, '')
90
- .replace(/-plugin$/, '')
91
- .replace(/[^a-z0-9-]/g, '-') || 'plugin'
92
- );
93
- }
94
-
95
85
  export async function exists(file) {
96
86
  return access(file).then(
97
87
  () => true,