@bitakit/cli 0.2.7 → 0.2.9
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 +15 -0
- package/package.json +3 -3
- package/skills/bitakit-app-development/references/plugins-and-pages.md +10 -0
- package/src/build.mjs +16 -13
- package/src/cli.mjs +17 -2
- package/src/doctor.mjs +34 -3
- package/src/inventory.mjs +66 -8
- package/src/project.mjs +2 -12
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.
|
|
3
|
+
"version": "0.2.9",
|
|
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.
|
|
29
|
-
"@bitakit/discovery": "^0.2.
|
|
28
|
+
"@bitakit/core": "^0.2.9",
|
|
29
|
+
"@bitakit/discovery": "^0.2.6",
|
|
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
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
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
|
-
/**
|
|
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
|
|
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 {
|
|
5
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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,
|