project-spec 0.11.2 → 0.12.0
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/README.md +3 -1
- package/bin/project-spec.mjs +21 -8
- package/package.json +1 -1
- package/skills/project-knowledge/SKILL.md +2 -2
- package/skills/project-knowledge/references/format.md +6 -2
- package/skills/project-knowledge/scripts/coverage.py +1 -1
- package/skills/project-knowledge/scripts/knowledge.py +138 -8
- package/skills/project-knowledge/scripts/maintain.py +19 -10
package/README.md
CHANGED
|
@@ -22,6 +22,7 @@ npx project-spec install --claude # or --codex
|
|
|
22
22
|
|
|
23
23
|
```text
|
|
24
24
|
Use the project-knowledge skill to build a knowledge vault for this repository.
|
|
25
|
+
Put it in project-spec/.
|
|
25
26
|
|
|
26
27
|
First take the inventory: every app and package, and every way into each one:
|
|
27
28
|
what a person can open, what another system can call, what runs on its own and
|
|
@@ -47,7 +48,7 @@ A big repository takes more than one session. To go on where the last one stoppe
|
|
|
47
48
|
Use the project-knowledge skill and continue the map from the inventory file.
|
|
48
49
|
```
|
|
49
50
|
|
|
50
|
-
The agent writes only Markdown
|
|
51
|
+
The agent writes only Markdown in that folder. Name any other folder in the prompt (`docs/spec`, `knowledge/shop`): the commands find the spec wherever it is, and `npx project-spec move --to DIR` moves it later without breaking its links. It does not change application code, commit or push. There is also a Claude Code plugin, a manual install and a way to pin one version for a team: see [Install and update](docs/install.md).
|
|
51
52
|
|
|
52
53
|
### What to ask next
|
|
53
54
|
|
|
@@ -135,6 +136,7 @@ npx project-spec serve # read the spec in the browser
|
|
|
135
136
|
npx project-spec coverage # what the code has that no page mentions yet
|
|
136
137
|
npx project-spec build --out FILE # the viewer as one file, to show on a server
|
|
137
138
|
npx project-spec instructions # the block that asks agents to keep the spec current
|
|
139
|
+
npx project-spec move --to DIR # move the spec to another folder of the repository
|
|
138
140
|
npx project-spec status # where the skill is installed and whether it is current
|
|
139
141
|
npx project-spec update # refresh the installed copies
|
|
140
142
|
```
|
package/bin/project-spec.mjs
CHANGED
|
@@ -18,7 +18,7 @@ const VIEWER_REL = 'assets/viewer.html';
|
|
|
18
18
|
const PACKAGE = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
|
|
19
19
|
const MARKER = '.project-spec.json'; // written into every copy: which version it is and what its files looked like
|
|
20
20
|
const SKIP = new Set(['__pycache__', '.DS_Store', MARKER]);
|
|
21
|
-
const KNOWLEDGE = new Set(['serve', 'build', 'check', 'snapshot']);
|
|
21
|
+
const KNOWLEDGE = new Set(['serve', 'build', 'check', 'snapshot', 'move']);
|
|
22
22
|
const MAINTAIN = new Set(['scan', 'receipt', 'finish']);
|
|
23
23
|
const COVERAGE = 'coverage'; // its own helper, which takes no command word
|
|
24
24
|
// Skills earlier versions shipped; project-knowledge took over what they did. spec-change (changing the product from
|
|
@@ -37,6 +37,8 @@ Read the spec
|
|
|
37
37
|
Write the viewer as one HTML file, to show the spec on a server.
|
|
38
38
|
project-spec check | snapshot [options]
|
|
39
39
|
The knowledge helper; --repo defaults to the current folder.
|
|
40
|
+
project-spec move --to DIR
|
|
41
|
+
Move the spec to another folder of the repository; links from its pages to your files are repointed.
|
|
40
42
|
project-spec coverage [--path FOLDER]... [--all]
|
|
41
43
|
What the code has that no spec page mentions yet: folders, messages and limits.
|
|
42
44
|
project-spec scan | receipt | finish [options]
|
|
@@ -292,17 +294,28 @@ const BLOCK_FILE = path.join(SKILLS, 'project-knowledge', 'references', 'agents.
|
|
|
292
294
|
const BLOCK_START = '<!-- project-spec:start -->';
|
|
293
295
|
const BLOCK_END = '<!-- project-spec:end -->';
|
|
294
296
|
|
|
295
|
-
// As the helpers do: the
|
|
297
|
+
// As the helpers do: the one folder that holds 00-index.md, at most three folders deep, outside hidden folders,
|
|
298
|
+
// dependencies and build output.
|
|
299
|
+
const NOT_A_VAULT_PLACE = new Set(['node_modules', 'vendor', 'dist', 'build', 'out', 'target', 'coverage', '__pycache__', 'venv', 'Pods']);
|
|
296
300
|
function findVault(repo) {
|
|
297
|
-
const base = path.join(repo, 'knowledge');
|
|
298
301
|
const found = [];
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
302
|
+
const look = (folder, depth) => {
|
|
303
|
+
let entries = [];
|
|
304
|
+
try {
|
|
305
|
+
entries = fs.readdirSync(folder, { withFileTypes: true }).filter(e => e.isDirectory() && !e.name.startsWith('.') && !NOT_A_VAULT_PLACE.has(e.name));
|
|
306
|
+
} catch {
|
|
307
|
+
return;
|
|
308
|
+
}
|
|
309
|
+
for (const entry of entries.sort((x, y) => (x.name < y.name ? -1 : 1))) {
|
|
310
|
+
const dir = path.join(folder, entry.name);
|
|
311
|
+
if (fs.existsSync(path.join(dir, '00-index.md'))) found.push(dir);
|
|
312
|
+
else if (depth < 3) look(dir, depth + 1);
|
|
303
313
|
}
|
|
314
|
+
};
|
|
315
|
+
look(repo, 1);
|
|
316
|
+
if (found.length !== 1) {
|
|
317
|
+
throw new Problem(`${found.length ? 'several vaults found (' + found.map(f => path.relative(repo, f)).join(', ') + ')' : 'no vault found: no folder with 00-index.md up to three folders deep'}; name the vault with --vault DIR`);
|
|
304
318
|
}
|
|
305
|
-
if (found.length !== 1) throw new Problem(`${found.length ? 'several vaults' : 'no vault'} found under knowledge/; name the vault with --vault DIR`);
|
|
306
319
|
return found[0];
|
|
307
320
|
}
|
|
308
321
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "project-spec",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.0",
|
|
4
4
|
"description": "Agent skills that read a repository and keep a spec people can read: one page per feature, every business rule numbered. Local viewer and one command to install and update the skills.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent-skills",
|
|
@@ -17,7 +17,7 @@ Read [the format contract](references/format.md) before writing pages or running
|
|
|
17
17
|
|
|
18
18
|
- `$SKILL_DIR`: the directory containing this `SKILL.md`; the helpers are in `$SKILL_DIR/scripts/`.
|
|
19
19
|
- `$REPO`: the root of the repository being documented.
|
|
20
|
-
- `$VAULT`: its vault
|
|
20
|
+
- `$VAULT`: its vault, a folder inside `$REPO`. Reuse an existing one, wherever it is. For a new one use the folder the person names; when they name none, create `project-spec/` at the root of `$REPO` (`project-spec/<product>/` when the repository holds several products that each need a spec) and say so. The helpers find the vault without being told when the repository has exactly one, up to three folders deep; otherwise pass `--vault`. To move a vault later, use `knowledge.py move --to <folder>`, which repoints the links from pages to repository files; never move the folder by hand.
|
|
21
21
|
|
|
22
22
|
## Keeping the layers apart
|
|
23
23
|
|
|
@@ -167,7 +167,7 @@ python3 "$SKILL_DIR/scripts/knowledge.py" snapshot --repo "$REPO" --vault "$VAUL
|
|
|
167
167
|
|
|
168
168
|
`check` validates structure and freshness; it cannot judge prose or coverage. `coverage.py` lists what the code has that no page mentions ([When a feature is finished](#when-a-feature-is-finished)). `--strict` turns freshness warnings into a failing exit status, for CI. In a working tree shared with someone else's uncommitted work, `--strict --ignore-dirty` still prints warnings for sources with uncommitted changes but does not fail on them when the accepted fingerprint equals the file at `HEAD` (the only drift is uncommitted); committed drift still fails, and it is not for CI ([details](references/format.md)). `serve` shows the vault in a browser and writes nothing. `snapshot` accepts source fingerprints as reviewed; run it only for pages you actually re-read against their sources, never to clear a warning. An initial reviewed pass may use `--all`.
|
|
169
169
|
|
|
170
|
-
To read the result, run `npx project-spec serve` in the repository (add `--vault` when it has several vaults
|
|
170
|
+
To read the result, run `npx project-spec serve` in the repository (add `--vault` when it has several vaults), or open the folder as an Obsidian vault. The viewer is not part of this skill, which holds only what writing a spec needs: it comes with the `project-spec` npm package. Where this copy of the skill has `assets/viewer.html`, or sits in a clone of the skills repository, `python3 <skill>/scripts/knowledge.py serve --repo <repository> --open` shows the same page without Node; without the viewer that command says so and names the other ways. When you hand over, offer to give the command a short name in the project: a `spec` script in `package.json` (`project-spec serve`), a `spec` target in a `Makefile`, or a shell alias. That file is outside the vault, so add it only when the person agrees. The viewer is one page on `127.0.0.1`; it reads the vault and the files the pages cite from disk on every page load, so it needs no build and shows the current state after a reload. It shows a note as written, under its title and summary, with the source files folded away at the end; an area page shows its notes with their summaries. So the first paragraph and the summary are what most readers see. Its **Copy for AI** turns a page and the reader's own words into a request for an agent that names the page file. It only copies text, so an agent that receives one still follows the skill it names, and a recheck or decision the reader states there is recorded under the reader's name, never as the agent's. If the vault has errors the page lists them instead. When the person wants the spec on a server for people without the repository, `npx project-spec build --out <file outside the vault>` (or `knowledge.py build` in a copy that has the viewer) writes that same viewer as one file ([options](references/format.md)); run it only when asked, never commit the file into the vault, and leave `--with-sources` out unless the person says everyone who can open the page may read the code.
|
|
171
171
|
|
|
172
172
|
Before handing over, read what you wrote as the person who will use it, not as its author. Open one area page and two of the notes you wrote or changed, and ask:
|
|
173
173
|
|
|
@@ -7,7 +7,7 @@ Plain Markdown, wikilinks and flat YAML properties. Use **JSON values inside YAM
|
|
|
7
7
|
## Layout
|
|
8
8
|
|
|
9
9
|
```text
|
|
10
|
-
knowledge/<project>/
|
|
10
|
+
project-spec/ or the folder the person chose; older vaults are in knowledge/<project>/
|
|
11
11
|
00-index.md start here
|
|
12
12
|
areas/ maps of related capabilities (spec)
|
|
13
13
|
notes/ source-backed behaviors and rules (spec)
|
|
@@ -166,6 +166,10 @@ The validator enforces these body rules:
|
|
|
166
166
|
5. A gap has six `##` sections with exactly these headings, each once: `Current behavior`, `Gap`, `Evidence`, `Recheck`, `Discussion`, `Decision`. Headings inside code fences do not count.
|
|
167
167
|
6. When `decision` is not `open`, `Decision` needs text; when `recheck` is not `not-checked`, `Recheck` needs text.
|
|
168
168
|
|
|
169
|
+
## Where the vault is
|
|
170
|
+
|
|
171
|
+
A vault is a folder of the repository that holds `00-index.md`. The person may put it anywhere; a new one goes to `project-spec/` at the root unless they name another folder. Nothing inside a page depends on that place except Markdown links from a page to a file of the repository, which are relative to the page. So a vault is moved with the helper, not by hand: `knowledge.py move --repo REPO --to FOLDER` moves the folder, repoints those links, writes `created` into each gap that lacks it (Git will show the page as new in its new place), removes the folder it left when nothing else is in it, and runs the checks. Page ids, wikilinks, `sources` and the reviewed fingerprints stay as they are. After a move, anything outside the vault that names the old folder is yours to update: a `--vault` in a script, the block in an agent instruction file.
|
|
172
|
+
|
|
169
173
|
## The inventory file
|
|
170
174
|
|
|
171
175
|
`.knowledge/inventory.md` is the checklist of a map: what the product has, and how far the spec has got with it. The agent writes it before the first page and keeps it true afterwards ([the rules](../SKILL.md#the-inventory-file)); no helper reads it, and like everything under `.knowledge/` it is not a page of the vault. It is committed with the vault, which is how a second session, or a second person, continues where the first one stopped.
|
|
@@ -246,7 +250,7 @@ Extract prose wikilinks, excluding inline and fenced code examples. Resolve full
|
|
|
246
250
|
|
|
247
251
|
Canonical Markdown must not contain raw merge conflicts. Validation rejects complete Git groups with a labeled opening marker, matching marker widths (including configured widths), and an optional diff3 base section, even inside code fences. Unlabeled or custom conflict formats are outside this detector; also inspect unresolved Git index entries. A `conflict` gap that records attributed claims and a next check is valid; it does not resolve them. See [concurrent merges](merge.md).
|
|
248
252
|
|
|
249
|
-
`serve` shows the vault in a browser: `knowledge.py serve --repo REPO [--vault VAULT] [--port N] [--open]`. Without `--vault`, this and every other command use the single vault
|
|
253
|
+
`serve` shows the vault in a browser: `knowledge.py serve --repo REPO [--vault VAULT] [--port N] [--open]`. Without `--vault`, this and every other command use the repository's single vault: the one folder that holds `00-index.md`, looked for up to three folders deep and not inside hidden folders, dependencies or build output. They stop with a message when there is none or several. It listens on `127.0.0.1` only (port 8757, or a free one when that is taken), answers only `/` and only when addressed as this machine, never writes, and builds the page again from disk on every request, so a reload shows the current files. When the vault has errors the page lists them. The page data is the graph above plus `live: true`, `vaultPath` (the vault's path relative to the repository), `history`, `pending` and `files`. `history` is the last 30 commits that touched vault pages (not `.knowledge/`), newest first, each `{"sha", "date", "subject", "pages", "more"}`; a page entry is `{"path", "status"}` with `status` `added`, `changed` or `removed`, plus `was` and `now` when the commit changed the page's `summary` (or, failing that, its `title`); at most 80 pages are listed per commit and `more` counts the rest. `pending` lists vault pages with uncommitted changes in the same `{"path", "status"}` shape. Both are empty outside a Git work tree. `files` is the text of the repository files that pages cite in `sources` or link to, keyed by repository-relative path, each `{"text", "truncated"}`. A file is included only when it is inside the repository and outside the vault, is not a credential path, and is UTF-8 text; one file is cut at 300,000 characters and all files together at 4,000,000, after which the rest stay ordinary links. The viewer opens a link to an included file in place: Markdown rendered, anything else as numbered lines, with the lines of a `#L10` or `#L10-L20` fragment marked.
|
|
250
254
|
|
|
251
255
|
`build` writes the same viewer as one file, for a server that shows the spec to people who do not have the repository: `knowledge.py build --repo REPO [--vault VAULT] --out FILE [--source-url URL] [--with-sources]`. `--out` must be a file outside the vault. The command stops with the `check` errors when the vault has any, and writes nothing then; freshness warnings do not stop it. The page data is the graph plus `built: true`, `commit` (the full `HEAD`, empty outside Git), `sourceUrl`, `vaultPath`, `history`, `pending` and `files`. `files` is empty unless `--with-sources` is given, because the text of cited files is source code. `--source-url` must be an `http(s)` address; `{commit}` in it is replaced by `HEAD`, and it is an error to name `{commit}` outside a Git work tree. `--allow-missing-sources` is for a build that sees only part of the repository (a Docker build context): a cited path where nothing exists is not an error and does not mark its page as changed, and the command lists those files; `check` and `snapshot` never accept it. On a built page a cited file whose text is not included is a link to `sourceUrl/<repository path>` (with `#L10-L20` when lines are named) in a new tab, or plain text when there is no `sourceUrl`; it is never a relative link, which would lead into the site that hosts the page. In a shallow clone the commit whose parents were not fetched is left out of `history` (by `serve` too), since Git would show every page as added there, and `build` says that the history is short.
|
|
252
256
|
|
|
@@ -146,7 +146,7 @@ def folders(files, prefixes=()):
|
|
|
146
146
|
def main(argv=None):
|
|
147
147
|
parser = argparse.ArgumentParser(description=__doc__.split('\n')[0])
|
|
148
148
|
parser.add_argument('--repo', required=True, type=Path)
|
|
149
|
-
parser.add_argument('--vault', type=Path, help='default: the single vault
|
|
149
|
+
parser.add_argument('--vault', type=Path, help='default: the single vault in the repository, a folder with 00-index.md')
|
|
150
150
|
parser.add_argument('--path', action='append', default=[], metavar='FOLDER',
|
|
151
151
|
help='only this folder or file of the repository, and list each sentence and limit no page mentions; repeatable')
|
|
152
152
|
parser.add_argument('--all', action='store_true', help='print every line instead of the first 40 folders or 60 items')
|
|
@@ -12,7 +12,7 @@ import sys
|
|
|
12
12
|
import subprocess
|
|
13
13
|
import tempfile
|
|
14
14
|
import unicodedata
|
|
15
|
-
from urllib.parse import unquote, urlsplit
|
|
15
|
+
from urllib.parse import quote, unquote, urlsplit
|
|
16
16
|
from pathlib import Path, PurePosixPath
|
|
17
17
|
|
|
18
18
|
TYPES = {'index', 'area', 'note', 'gap', 'plan', 'run'}
|
|
@@ -711,17 +711,138 @@ def viewer_html(payload):
|
|
|
711
711
|
return template.replace('__KNOWLEDGE_DATA__', serialized)
|
|
712
712
|
|
|
713
713
|
|
|
714
|
+
VAULT_DEPTH = 3 # project-spec/, knowledge/<product>/ and docs/<product>/spec/ are all within reach
|
|
715
|
+
NOT_A_VAULT_PLACE = {'node_modules', 'vendor', 'dist', 'build', 'out', 'target', 'coverage', '__pycache__', 'venv', 'Pods'}
|
|
716
|
+
|
|
717
|
+
|
|
714
718
|
def find_vault(repo):
|
|
715
|
-
"""The vault
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
+
"""The repository's vault when it has exactly one: a folder that holds `00-index.md`, wherever the person put it.
|
|
720
|
+
|
|
721
|
+
Looks at most three folders deep and not inside hidden folders, dependencies or build output, so a vault that
|
|
722
|
+
belongs to something nested deeper (an example project, a package's own docs) is not taken for the repository's.
|
|
723
|
+
"""
|
|
724
|
+
found = []
|
|
725
|
+
|
|
726
|
+
def look(folder, depth):
|
|
727
|
+
try:
|
|
728
|
+
entries = sorted(e for e in folder.iterdir()
|
|
729
|
+
if e.is_dir() and not e.is_symlink() and not e.name.startswith('.') and e.name not in NOT_A_VAULT_PLACE)
|
|
730
|
+
except OSError:
|
|
731
|
+
return
|
|
732
|
+
for entry in entries:
|
|
733
|
+
if (entry / '00-index.md').is_file():
|
|
734
|
+
found.append(entry) # nothing inside a vault is another vault
|
|
735
|
+
elif depth < VAULT_DEPTH:
|
|
736
|
+
look(entry, depth + 1)
|
|
737
|
+
|
|
738
|
+
look(repo, 1)
|
|
719
739
|
if len(found) != 1:
|
|
720
|
-
raise ValueError(('no vault found
|
|
740
|
+
raise ValueError(('no vault found: no folder with 00-index.md up to three folders deep' if not found else
|
|
721
741
|
'several vaults found (' + ', '.join(p.relative_to(repo).as_posix() for p in found) + ')') + '; pass --vault')
|
|
722
742
|
return found[0]
|
|
723
743
|
|
|
724
744
|
|
|
745
|
+
def repoint(text, old_dir, new_dir, old_vault):
|
|
746
|
+
"""`text` of a page that sat in `old_dir` and now sits in `new_dir`, with the links that leave the vault repointed.
|
|
747
|
+
|
|
748
|
+
All three are absolute POSIX paths. A link to another page of the vault is relative to something that moved with
|
|
749
|
+
it, so it stays as written; a link to a file of the repository is rewritten so it names the same file from the
|
|
750
|
+
new place. Links in code are left alone. Returns (text, how many links changed).
|
|
751
|
+
"""
|
|
752
|
+
changed = 0
|
|
753
|
+
|
|
754
|
+
def target(match):
|
|
755
|
+
nonlocal changed
|
|
756
|
+
raw = match.group(1)
|
|
757
|
+
angle = raw.startswith('<')
|
|
758
|
+
inner = raw[1:-1] if angle else raw
|
|
759
|
+
cut = re.search(r'[?#]', inner)
|
|
760
|
+
path, tail = (inner[:cut.start()], inner[cut.start():]) if cut else (inner, '')
|
|
761
|
+
where = unquote(path)
|
|
762
|
+
if not where or where.startswith('/') or SCHEME.match(where):
|
|
763
|
+
return match.group(0)
|
|
764
|
+
absolute = posixpath.normpath(posixpath.join(old_dir, where))
|
|
765
|
+
if absolute == old_vault or absolute.startswith(old_vault + '/'):
|
|
766
|
+
return match.group(0)
|
|
767
|
+
fresh = posixpath.relpath(absolute, new_dir)
|
|
768
|
+
fresh = fresh if angle else quote(fresh, safe="/-._~!$&'()*+,;=:@")
|
|
769
|
+
if fresh == path:
|
|
770
|
+
return match.group(0)
|
|
771
|
+
changed += 1
|
|
772
|
+
return match.group(0)[:match.start(1) - match.start(0)] + (f'<{fresh}{tail}>' if angle else fresh + tail)
|
|
773
|
+
|
|
774
|
+
lines = []
|
|
775
|
+
for line, in_code in lines_with_code(text):
|
|
776
|
+
if not in_code:
|
|
777
|
+
# an inline code span is not a link either
|
|
778
|
+
pieces = re.split(r'(`+.*?`+)', line)
|
|
779
|
+
line = ''.join(piece if i % 2 else MD_REF.sub(target, MD_LINK.sub(target, piece)) for i, piece in enumerate(pieces))
|
|
780
|
+
lines.append(line)
|
|
781
|
+
return '\n'.join(lines), changed
|
|
782
|
+
|
|
783
|
+
|
|
784
|
+
def move_vault(repo, vault, dest):
|
|
785
|
+
"""Move the vault to `dest`, another folder of the same repository, and keep it true: links from pages to files
|
|
786
|
+
of the repository are repointed, and each gap keeps the day it appeared. Returns a list of lines to print.
|
|
787
|
+
|
|
788
|
+
Page ids, wikilinks, `sources` and the reviewed fingerprints do not depend on where the vault is, so nothing
|
|
789
|
+
else changes. Raises ValueError with the reason when the move cannot be made; nothing is touched then.
|
|
790
|
+
"""
|
|
791
|
+
import shutil
|
|
792
|
+
dest = Path(os.path.abspath(dest))
|
|
793
|
+
if dest == vault:
|
|
794
|
+
raise ValueError('the vault is already there')
|
|
795
|
+
if not dest.is_relative_to(repo) or dest == repo:
|
|
796
|
+
raise ValueError('--to must be a folder inside the repository')
|
|
797
|
+
if dest.is_relative_to(vault):
|
|
798
|
+
raise ValueError('--to must not be inside the vault it moves')
|
|
799
|
+
if dest.exists() and (not dest.is_dir() or any(dest.iterdir())):
|
|
800
|
+
raise ValueError(f'{dest.relative_to(repo).as_posix()} already exists and is not empty')
|
|
801
|
+
first = added_dates(repo, vault)
|
|
802
|
+
edits, links, pages, dated = {}, 0, 0, 0
|
|
803
|
+
for file in sorted(vault.rglob('*.md')):
|
|
804
|
+
rel = file.relative_to(vault)
|
|
805
|
+
if any(part in {'.obsidian', '.trash'} for part in rel.parts) or file.is_symlink():
|
|
806
|
+
continue
|
|
807
|
+
try:
|
|
808
|
+
before = file.read_bytes().decode('utf-8')
|
|
809
|
+
except (OSError, UnicodeDecodeError):
|
|
810
|
+
continue
|
|
811
|
+
after, count = repoint(before.replace('\r\n', '\n'), (vault / rel).parent.as_posix(), (dest / rel).parent.as_posix(), vault.as_posix())
|
|
812
|
+
# Git will show the page as new in its new place, so a gap that has no `created` gets the day it first appeared.
|
|
813
|
+
head = re.match(r'---\n(.*?)\n---\n', after, re.S)
|
|
814
|
+
day = first.get(rel.as_posix())
|
|
815
|
+
if head and day and re.search(r'^type:\s*"gap"\s*$', head.group(1), re.M) and not re.search(r'^created:', head.group(1), re.M):
|
|
816
|
+
after = re.sub(r'^(type:\s*"gap"\s*)$', lambda m: m.group(1) + f'\ncreated: "{day}"', after, count=1, flags=re.M)
|
|
817
|
+
dated += 1
|
|
818
|
+
if count:
|
|
819
|
+
links, pages = links + count, pages + 1
|
|
820
|
+
if after != before.replace('\r\n', '\n'):
|
|
821
|
+
edits[rel] = after
|
|
822
|
+
dest.parent.mkdir(parents=True, exist_ok=True)
|
|
823
|
+
if dest.exists():
|
|
824
|
+
dest.rmdir()
|
|
825
|
+
shutil.move(str(vault), str(dest))
|
|
826
|
+
for rel, text in edits.items():
|
|
827
|
+
atomic_write(dest / rel, text)
|
|
828
|
+
old, new = vault.relative_to(repo).as_posix(), dest.relative_to(repo).as_posix()
|
|
829
|
+
lines = [f'move: {old} -> {new}; {links} links to repository files repointed on {pages} pages'
|
|
830
|
+
+ (f'; {dated} gaps given the day they first appeared' if dated else '')]
|
|
831
|
+
_, _, errors, warnings, _ = load_vault(repo, dest)
|
|
832
|
+
lines.append(f'move: check finds {len(errors)} errors and {len(warnings)} warnings in the new place')
|
|
833
|
+
lines += [f' {error}' for error in errors[:20]]
|
|
834
|
+
left = vault.parent
|
|
835
|
+
if left != repo and left.is_dir() and left != dest.parent:
|
|
836
|
+
rest = sorted(p.name for p in left.iterdir())
|
|
837
|
+
if rest:
|
|
838
|
+
lines.append(f'move: {left.relative_to(repo).as_posix()}/ still holds {", ".join(rest)}')
|
|
839
|
+
else:
|
|
840
|
+
left.rmdir() # nothing of anyone's is left in it
|
|
841
|
+
lines.append(f'move: now update what names the old folder: a `--vault {old}` in your scripts, and the block in AGENTS.md or CLAUDE.md '
|
|
842
|
+
'(`project-spec instructions --file ...` writes it again)')
|
|
843
|
+
return lines
|
|
844
|
+
|
|
845
|
+
|
|
725
846
|
HISTORY_COMMITS = 30 # commits shown under Recent changes
|
|
726
847
|
HISTORY_PAGES = 80 # pages listed for one commit
|
|
727
848
|
_history_cache = {}
|
|
@@ -954,13 +1075,14 @@ def make_server(repo, vault, port):
|
|
|
954
1075
|
|
|
955
1076
|
def main(argv=None):
|
|
956
1077
|
parser = argparse.ArgumentParser()
|
|
957
|
-
parser.add_argument('command', choices=['check', 'snapshot', 'serve', 'build'])
|
|
1078
|
+
parser.add_argument('command', choices=['check', 'snapshot', 'serve', 'build', 'move'])
|
|
958
1079
|
parser.add_argument('--repo', required=True, type=Path)
|
|
959
|
-
parser.add_argument('--vault', type=Path, help='default: the single vault
|
|
1080
|
+
parser.add_argument('--vault', type=Path, help='default: the single vault in the repository, a folder with 00-index.md')
|
|
960
1081
|
parser.add_argument('--strict', action='store_true', help='fail check when freshness warnings exist')
|
|
961
1082
|
parser.add_argument('--port', type=int, default=8757, help='serve: port on 127.0.0.1 (another free port is used if it is taken)')
|
|
962
1083
|
parser.add_argument('--open', action='store_true', help='serve: open the page in the default browser')
|
|
963
1084
|
parser.add_argument('--out', type=Path, help='build: the HTML file to write, outside the vault')
|
|
1085
|
+
parser.add_argument('--to', type=Path, metavar='DIR', help='move: the folder of the repository the vault moves to')
|
|
964
1086
|
parser.add_argument('--viewer', type=Path, metavar='FILE',
|
|
965
1087
|
help='serve, build: a page of your own instead of the viewer; it gets the data where it says __KNOWLEDGE_DATA__')
|
|
966
1088
|
parser.add_argument('--with-sources', action='store_true', help='build: include the text of the repository files the pages cite')
|
|
@@ -995,6 +1117,14 @@ def main(argv=None):
|
|
|
995
1117
|
parser.error('repo and vault must be existing directories')
|
|
996
1118
|
if args.viewer and args.command not in ('serve', 'build'):
|
|
997
1119
|
parser.error('--viewer is only for serve and build')
|
|
1120
|
+
if (args.command == 'move') != bool(args.to):
|
|
1121
|
+
parser.error('move requires --to DIR' if args.command == 'move' else '--to is only for move')
|
|
1122
|
+
if args.command == 'move':
|
|
1123
|
+
try:
|
|
1124
|
+
print('\n'.join(move_vault(repo, vault, args.to if args.to.is_absolute() else repo / args.to)))
|
|
1125
|
+
except (OSError, ValueError) as exc:
|
|
1126
|
+
parser.error(str(exc))
|
|
1127
|
+
return 0
|
|
998
1128
|
if args.command in ('serve', 'build'):
|
|
999
1129
|
global VIEWER
|
|
1000
1130
|
VIEWER = args.viewer.resolve() if args.viewer else None
|
|
@@ -53,18 +53,23 @@ def jsonbytes(value):
|
|
|
53
53
|
return (json.dumps(value, ensure_ascii=True, indent=2, sort_keys=True) + '\n').encode()
|
|
54
54
|
|
|
55
55
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
parts = p.parts
|
|
59
|
-
bundle_metadata = vault_rel.startswith('knowledge/') and path in {'knowledge/README.md', 'knowledge/.gitignore'}
|
|
60
|
-
return bool(parts) and not bundle_metadata and not knowledge.credential_path(path) and not (path == vault_rel or path.startswith(vault_rel + '/')) and not (path == 'knowledge/tooling/project-knowledge' or path.startswith('knowledge/tooling/project-knowledge/')) and not any(knowledge.fold(x) in {'.git', 'node_modules', '.next', 'dist', 'build', 'coverage', '__pycache__'} for x in parts)
|
|
56
|
+
# Where a copy of this skill may sit inside the repository: updating it is not a change of the application.
|
|
57
|
+
SKILL_COPIES = tuple(base + '/project-knowledge' for base in ('knowledge/tooling', '.claude/skills', '.codex/skills', '.agents/skills'))
|
|
61
58
|
|
|
62
59
|
|
|
63
60
|
def housekeeping(path, vault_rel):
|
|
64
|
-
"""Paths a sync never queues because they are the vault, the
|
|
61
|
+
"""Paths a sync never queues because they are the vault, a copy of the skill or their wrapper files."""
|
|
65
62
|
if vault_rel.startswith('knowledge/') and path in {'knowledge/README.md', 'knowledge/.gitignore'}:
|
|
66
63
|
return True
|
|
67
|
-
return any(path == base or path.startswith(base + '/') for base in (vault_rel,
|
|
64
|
+
return any(path == base or path.startswith(base + '/') for base in (vault_rel, *SKILL_COPIES))
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def relevant(path, vault_rel):
|
|
68
|
+
parts = Path(path).parts
|
|
69
|
+
return (bool(parts) and not knowledge.credential_path(path) and not housekeeping(path, vault_rel)
|
|
70
|
+
and not any(knowledge.fold(x) in {'.git', 'node_modules', '.next', 'dist', 'build', 'coverage', '__pycache__'} for x in parts))
|
|
71
|
+
|
|
72
|
+
|
|
68
73
|
|
|
69
74
|
|
|
70
75
|
def retarget_hint(repo, vault, target):
|
|
@@ -512,16 +517,20 @@ def main():
|
|
|
512
517
|
parser = argparse.ArgumentParser()
|
|
513
518
|
subs = parser.add_subparsers(dest='command', required=True)
|
|
514
519
|
rp = subs.add_parser('receipt')
|
|
515
|
-
rp.add_argument('--repo', required=True, type=Path); rp.add_argument('--vault',
|
|
520
|
+
rp.add_argument('--repo', required=True, type=Path); rp.add_argument('--vault', type=Path)
|
|
516
521
|
rp.add_argument('--plan', required=True, type=Path); rp.add_argument('--out', required=True, type=Path)
|
|
517
522
|
rp.add_argument('--run', type=Path)
|
|
518
523
|
for name in ('scan', 'finish'):
|
|
519
|
-
p = subs.add_parser(name); p.add_argument('--repo', required=True, type=Path); p.add_argument('--vault',
|
|
524
|
+
p = subs.add_parser(name); p.add_argument('--repo', required=True, type=Path); p.add_argument('--vault', type=Path)
|
|
520
525
|
if name == 'scan':
|
|
521
526
|
p.add_argument('--target'); p.add_argument('--write-status', action='store_true'); p.add_argument('--json', action='store_true')
|
|
522
527
|
else:
|
|
523
528
|
p.add_argument('--plan', required=True, type=Path); p.add_argument('--review', required=True, type=Path)
|
|
524
|
-
args = parser.parse_args(); repo = args.repo.resolve()
|
|
529
|
+
args = parser.parse_args(); repo = args.repo.resolve()
|
|
530
|
+
try:
|
|
531
|
+
vault = args.vault.resolve() if args.vault else knowledge.find_vault(repo)
|
|
532
|
+
except ValueError as exc:
|
|
533
|
+
parser.error(str(exc))
|
|
525
534
|
if args.command == 'receipt':
|
|
526
535
|
print(receipt(repo, vault, args.plan, args.out, args.run))
|
|
527
536
|
elif args.command == 'scan':
|