akm-cli 0.10.261128 → 0.10.261129
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/CHANGELOG.md +22 -0
- package/dist/cli.js +2 -0
- package/dist/commands/agent/contribute-cli.js +7 -1
- package/dist/commands/backups-cli.js +103 -0
- package/dist/commands/health.js +1 -34
- package/dist/commands/improve/reflect-noise.js +0 -1
- package/dist/commands/lint/base-linter.js +24 -48
- package/dist/commands/lint/bundle-skip.js +27 -0
- package/dist/commands/lint/index.js +83 -45
- package/dist/commands/lint/tracked-secrets.js +43 -0
- package/dist/commands/lint/types.js +58 -0
- package/dist/commands/proposal/repository.js +5 -1
- package/dist/commands/sources/stash-skeleton.js +7 -26
- package/dist/core/adapter/adapters/akm-adapter.js +2 -2
- package/dist/core/adapter/adapters/akm-workflow-adapter.js +6 -1
- package/dist/core/adapter/adapters/shared.js +13 -25
- package/dist/core/asset/lint-text.js +14 -13
- package/dist/core/asset/stale-path.js +63 -0
- package/dist/core/config/schema/sources-bundles.js +3 -0
- package/dist/output/shapes/passthrough.js +1 -0
- package/dist/output/text/lint-format.js +90 -1
- package/dist/output/text/migrate.js +5 -0
- package/dist/scripts/akm-migrate-node.js +1149 -791
- package/dist/scripts/akm-migrate.js +1149 -791
- package/dist/sources/include.js +1 -1
- package/dist/sources/snapshot-fetchers/website-ingest.js +0 -2
- package/dist/workspace/backups.js +21 -0
- package/dist/workspace/cli-child.js +5 -1
- package/dist/workspace-node.mjs +2 -0
- package/dist/workspace.d.ts +4 -0
- package/dist/workspace.js +1 -0
- package/docs/architecture/internals/health-advisories.md +1 -2
- package/docs/guides/bundles.md +5 -4
- package/docs/integration/bundling-akm.md +9 -1
- package/docs/reference/asset-types.md +1 -2
- package/docs/reference/cli.md +83 -3
- package/docs/reference/configuration.md +8 -2
- package/docs/reference/data-and-telemetry.md +1 -0
- package/docs/reference/env-and-secrets.md +9 -4
- package/docs/reference/website-sources.md +2 -2
- package/docs/reference/workspace.md +1 -0
- package/package.json +1 -1
- package/schemas/akm-config.json +34 -0
- package/dist/commands/health/stash-exposure.js +0 -64
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
// This Source Code Form is subject to the terms of the Mozilla Public
|
|
2
|
+
// License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
3
|
+
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
|
|
4
|
+
/**
|
|
5
|
+
* The `stale-path` rule, shared by every lint surface: which absolute paths
|
|
6
|
+
* this machine can judge, and what an agent needs to find and correct one.
|
|
7
|
+
* Only the current user's home, a configured bundle or project root, and
|
|
8
|
+
* `/tmp` are judged; any other path belongs to some other host or user.
|
|
9
|
+
*/
|
|
10
|
+
import fs from "node:fs";
|
|
11
|
+
import os from "node:os";
|
|
12
|
+
import path from "node:path";
|
|
13
|
+
import { bundleContentRoots } from "../config/config-sources.js";
|
|
14
|
+
import { expandProjectPath } from "../config/schema/projects.js";
|
|
15
|
+
import { findCurrentPathReferences } from "./lint-text.js";
|
|
16
|
+
/** The roots that make a path judgeable: the user's home, every configured bundle and project, and `extraRoots`. */
|
|
17
|
+
export function stalePathRoots(config, ...extraRoots) {
|
|
18
|
+
const projectPaths = Object.values(config.projects ?? {}).flatMap((project) => project.paths ?? []);
|
|
19
|
+
return [
|
|
20
|
+
os.homedir(),
|
|
21
|
+
...bundleContentRoots(config).map((bundle) => bundle.contentRoot),
|
|
22
|
+
...projectPaths.map(expandProjectPath),
|
|
23
|
+
...extraRoots,
|
|
24
|
+
];
|
|
25
|
+
}
|
|
26
|
+
function isUnder(candidate, root) {
|
|
27
|
+
return candidate === root || candidate.startsWith(root.endsWith("/") ? root : `${root}/`);
|
|
28
|
+
}
|
|
29
|
+
function nearestExistingDirectory(candidate) {
|
|
30
|
+
let dir = path.dirname(candidate);
|
|
31
|
+
while (dir !== path.dirname(dir) && !fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory()) {
|
|
32
|
+
dir = path.dirname(dir);
|
|
33
|
+
}
|
|
34
|
+
return dir;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* The stale paths in `text` (whose first line is file line `firstLine`): paths presented as current
|
|
38
|
+
* guidance that do not exist and that this machine can judge. `bundleRoot` is the bundle the text
|
|
39
|
+
* belongs to; a path under it also gets its portable `$AKM_BUNDLE_DIR` spelling in the detail.
|
|
40
|
+
*/
|
|
41
|
+
export function findStalePaths(text, firstLine, roots, bundleRoot) {
|
|
42
|
+
const findings = [];
|
|
43
|
+
for (const { path: candidate, line, lineText } of findCurrentPathReferences(text, firstLine)) {
|
|
44
|
+
const managed = roots.some((root) => isUnder(candidate, root));
|
|
45
|
+
const ephemeral = !managed && candidate.startsWith("/tmp/");
|
|
46
|
+
if (!managed && !ephemeral)
|
|
47
|
+
continue;
|
|
48
|
+
if (fs.existsSync(candidate))
|
|
49
|
+
continue;
|
|
50
|
+
const portable = isUnder(candidate, bundleRoot)
|
|
51
|
+
? ` (portable form: $AKM_BUNDLE_DIR${candidate.slice(bundleRoot.length)})`
|
|
52
|
+
: "";
|
|
53
|
+
findings.push({
|
|
54
|
+
path: candidate,
|
|
55
|
+
line,
|
|
56
|
+
lineText,
|
|
57
|
+
nearestExisting: nearestExistingDirectory(candidate),
|
|
58
|
+
reason: ephemeral ? "ephemeral" : "missing",
|
|
59
|
+
detail: `${ephemeral ? "ephemeral" : "nonexistent"} path: ${candidate}${portable}`,
|
|
60
|
+
});
|
|
61
|
+
}
|
|
62
|
+
return findings;
|
|
63
|
+
}
|
|
@@ -136,6 +136,9 @@ export const BundleConfigEntrySchema = z
|
|
|
136
136
|
// (e.g. registryId `github:owner/repo` → key `repo`).
|
|
137
137
|
registryId: z.string().min(1).optional(),
|
|
138
138
|
components: z.record(z.string().min(1), BundleComponentConfigSchema).optional(),
|
|
139
|
+
// Lint rules to skip, per rule, for the assets whose bundle-relative path matches one of the
|
|
140
|
+
// globs (`**` is the whole bundle). A rule name lint does not know is warned about and ignored.
|
|
141
|
+
lint: z.object({ skip: z.record(z.string(), z.array(z.string())).optional() }).optional(),
|
|
139
142
|
})
|
|
140
143
|
.passthrough()
|
|
141
144
|
.superRefine((entry, ctx) => {
|
|
@@ -34,6 +34,92 @@ function renderIssueSection(title, issues) {
|
|
|
34
34
|
return [`${title}: (none)`];
|
|
35
35
|
return [`${title} (${issues.length})`, ...renderStatusEntries(issues.map(issueEntry))];
|
|
36
36
|
}
|
|
37
|
+
/** Whether `--fix` repairs a rule's findings, and the one-line way to fix them otherwise. */
|
|
38
|
+
const RULE_HELP = {
|
|
39
|
+
"unquoted-colon": { fix: true, how: "quote the description value" },
|
|
40
|
+
"missing-updated": { fix: true, how: "add `updated: YYYY-MM-DD` to the frontmatter" },
|
|
41
|
+
"orphaned-stub": { fix: true, how: "write the stub's derived file or delete the stub" },
|
|
42
|
+
"placeholder-stub": { fix: true, how: "replace the placeholder text or delete the file" },
|
|
43
|
+
"missing-name-or-type": { fix: false, how: "add the missing `name` or `type` to the frontmatter" },
|
|
44
|
+
"missing-type": { fix: false, how: "add `type` to the frontmatter" },
|
|
45
|
+
"stale-path": {
|
|
46
|
+
fix: false,
|
|
47
|
+
how: 'correct the path; if the line records the past or an example, say so on the line ("formerly", "for example") or put it under a History/Examples heading',
|
|
48
|
+
},
|
|
49
|
+
"missing-skill-md": { fix: false, how: "add a SKILL.md to the skill directory" },
|
|
50
|
+
"invalid-task-yaml": { fix: false, how: "use the .yml extension and valid task YAML" },
|
|
51
|
+
"missing-ref": { fix: false, how: "correct the ref or create the asset it names" },
|
|
52
|
+
"redacted-content": { fix: false, how: "restore the original text from version history" },
|
|
53
|
+
"dangerous-env-key": { fix: false, how: "remove the key from the env file" },
|
|
54
|
+
"tracked-secrets": {
|
|
55
|
+
fix: false,
|
|
56
|
+
how: "`git rm --cached` the file, or list its path under `lint.skip.tracked-secrets`",
|
|
57
|
+
},
|
|
58
|
+
"missing-category": { fix: false, how: "add the fact's `category`" },
|
|
59
|
+
"invalid-workflow-structure": { fix: false, how: "correct the workflow as the detail says" },
|
|
60
|
+
};
|
|
61
|
+
/** Up to three folders (two directory levels at most) holding most of `files`, with their counts. */
|
|
62
|
+
function topFolders(files) {
|
|
63
|
+
const counts = new Map();
|
|
64
|
+
for (const file of files) {
|
|
65
|
+
const folder = file.split(/[\\/]/).slice(0, -1).slice(0, 2).join("/") || ".";
|
|
66
|
+
counts.set(folder, (counts.get(folder) ?? 0) + 1);
|
|
67
|
+
}
|
|
68
|
+
return [...counts]
|
|
69
|
+
.sort((a, b) => b[1] - a[1])
|
|
70
|
+
.slice(0, 3)
|
|
71
|
+
.map(([folder, count]) => `${folder} (${count})`)
|
|
72
|
+
.join(", ");
|
|
73
|
+
}
|
|
74
|
+
const count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
|
|
75
|
+
/** One line per rule: findings, assets, where they cluster, whether `--fix` repairs them, and how to fix them. */
|
|
76
|
+
function renderRuleSummary(flagged, byRule) {
|
|
77
|
+
if (flagged.length === 0)
|
|
78
|
+
return ["flagged: (none)"];
|
|
79
|
+
const rules = Object.entries(byRule).sort((a, b) => b[1].findings - a[1].findings);
|
|
80
|
+
return [
|
|
81
|
+
`flagged (${flagged.length}); list one rule with \`akm lint --rule <rule>\``,
|
|
82
|
+
...rules.map(([rule, { findings, assets }]) => {
|
|
83
|
+
const help = RULE_HELP[rule];
|
|
84
|
+
const folders = topFolders(flagged.filter((issue) => issue.issue === rule).map((issue) => issue.file));
|
|
85
|
+
return (` ${rule}: ${count(findings, "finding")} in ${count(assets, "asset")}; ${folders}; ` +
|
|
86
|
+
`--fix ${help?.fix ? "fixes it" : "does not fix it"}; ${help?.how ?? "see the detail with --rule"}`);
|
|
87
|
+
}),
|
|
88
|
+
];
|
|
89
|
+
}
|
|
90
|
+
/** `lineText` cut to a window around `path` when the line is long, so one long line stays readable. */
|
|
91
|
+
function excerpt(lineText, path) {
|
|
92
|
+
if (lineText.length <= 200)
|
|
93
|
+
return lineText;
|
|
94
|
+
const start = Math.max(0, lineText.indexOf(path) - 80);
|
|
95
|
+
return `${start > 0 ? "..." : ""}${lineText.slice(start, start + 200)}...`;
|
|
96
|
+
}
|
|
97
|
+
/** One rule's findings grouped by asset, each with where it is and what to change. */
|
|
98
|
+
function renderRuleListing(rule, flagged) {
|
|
99
|
+
if (flagged.length === 0)
|
|
100
|
+
return [`${rule}: no findings`];
|
|
101
|
+
const byFile = new Map();
|
|
102
|
+
for (const issue of flagged)
|
|
103
|
+
byFile.set(issue.file, [...(byFile.get(issue.file) ?? []), issue]);
|
|
104
|
+
const help = RULE_HELP[rule];
|
|
105
|
+
const lines = [`${rule}: ${count(flagged.length, "finding")} in ${count(byFile.size, "asset")}`];
|
|
106
|
+
if (help)
|
|
107
|
+
lines.push(`how to fix: ${help.how}`);
|
|
108
|
+
for (const [file, issues] of byFile) {
|
|
109
|
+
const ref = issues[0]?.ref;
|
|
110
|
+
lines.push("", ref ? `${ref} (${file})` : file);
|
|
111
|
+
for (const issue of issues) {
|
|
112
|
+
const at = typeof issue.line === "number" ? `line ${issue.line} ` : "";
|
|
113
|
+
if (issue.path === undefined) {
|
|
114
|
+
lines.push(` ${at}${issue.detail}`);
|
|
115
|
+
continue;
|
|
116
|
+
}
|
|
117
|
+
lines.push(` ${at}${issue.path} ${issue.reason}; nearest existing: ${issue.nearestExisting}`);
|
|
118
|
+
lines.push(` ${excerpt(issue.lineText ?? "", issue.path)}`);
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
return lines;
|
|
122
|
+
}
|
|
37
123
|
export function formatLintPlain(r) {
|
|
38
124
|
if (r === null || typeof r !== "object")
|
|
39
125
|
return null;
|
|
@@ -49,7 +135,10 @@ export function formatLintPlain(r) {
|
|
|
49
135
|
// Flagged (still needs attention) surfaces before warnings (advisory,
|
|
50
136
|
// non-fatal) and fixed (already handled), so a scan of the output hits the
|
|
51
137
|
// actionable items first.
|
|
52
|
-
|
|
138
|
+
const rule = typeof r.rule === "string" ? r.rule : undefined;
|
|
139
|
+
lines.push("", ...(rule
|
|
140
|
+
? renderRuleListing(rule, flagged)
|
|
141
|
+
: renderRuleSummary(flagged, (r.byRule ?? {}))));
|
|
53
142
|
lines.push("", ...renderIssueSection("warnings", warnings));
|
|
54
143
|
lines.push("", ...renderIssueSection("fixed", fixed));
|
|
55
144
|
return lines.join("\n").trim();
|
|
@@ -32,6 +32,8 @@ export function formatMigratePlain(result) {
|
|
|
32
32
|
const refs = plan.assetContentRefs;
|
|
33
33
|
lines.push(` asset content refs: ${refs.refs} in ${refs.changed} file(s) change, ${refs.skipped} skipped, ${refs.shadowed?.length ?? 0} shadowed`);
|
|
34
34
|
}
|
|
35
|
+
if (plan.bundlePolicy)
|
|
36
|
+
lines.push(` bundle policy: ${plan.bundlePolicy.changed} change(s)`);
|
|
35
37
|
if (plan.blockers?.length) {
|
|
36
38
|
lines.push("", "blockers:", ...plan.blockers.map((blocker) => ` - ${blocker}`));
|
|
37
39
|
}
|
|
@@ -41,6 +43,9 @@ export function formatMigratePlain(result) {
|
|
|
41
43
|
if (plan.assetEngineKeys?.notes?.length) {
|
|
42
44
|
lines.push("", "engine name notes:", ...plan.assetEngineKeys.notes.map((note) => ` - ${note}`));
|
|
43
45
|
}
|
|
46
|
+
if (plan.bundlePolicy?.notes?.length) {
|
|
47
|
+
lines.push("", "bundle policy notes:", ...plan.bundlePolicy.notes.map((note) => ` - ${note}`));
|
|
48
|
+
}
|
|
44
49
|
if (plan.assetContentRefs?.shadowed?.length) {
|
|
45
50
|
lines.push("", "shadowed refs (another file holds the old spelling as its ref; not rewritten, resolve them by hand):", ...plan.assetContentRefs.shadowed.map((ref) => ` - ${ref.bundleId}: ${ref.from} (now ${ref.to})`));
|
|
46
51
|
}
|