project-spec 0.0.0-stage → 0.7.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/LICENSE +21 -0
- package/README.md +323 -2
- package/bin/project-spec.mjs +279 -0
- package/package.json +40 -4
- package/skills/project-knowledge/LICENSE +21 -0
- package/skills/project-knowledge/SKILL.md +139 -0
- package/skills/project-knowledge/agents/openai.yaml +4 -0
- package/skills/project-knowledge/assets/viewer.html +3615 -0
- package/skills/project-knowledge/references/audit.md +52 -0
- package/skills/project-knowledge/references/format.md +215 -0
- package/skills/project-knowledge/references/gaps.md +159 -0
- package/skills/project-knowledge/references/investigate.md +33 -0
- package/skills/project-knowledge/references/merge.md +70 -0
- package/skills/project-knowledge/references/migrate.md +56 -0
- package/skills/project-knowledge/references/sync.md +102 -0
- package/skills/project-knowledge/scripts/knowledge.py +929 -0
- package/skills/project-knowledge/scripts/maintain.py +545 -0
- package/skills/project-knowledge/scripts/merge.py +182 -0
- package/skills/project-knowledge/scripts/test_knowledge.py +1121 -0
- package/skills/project-knowledge/scripts/test_maintain.py +864 -0
- package/skills/project-knowledge/scripts/test_merge.py +165 -0
- package/skills/spec-change/LICENSE +21 -0
- package/skills/spec-change/SKILL.md +63 -0
- package/skills/spec-change/agents/openai.yaml +4 -0
- package/skills/spec-change/references/gaps.md +159 -0
- package/skills/spec-change/references/plan.md +40 -0
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Inspect two committed vault histories without applying or writing changes."""
|
|
3
|
+
import argparse
|
|
4
|
+
import json
|
|
5
|
+
import os
|
|
6
|
+
from pathlib import Path, PurePosixPath
|
|
7
|
+
import re
|
|
8
|
+
import subprocess
|
|
9
|
+
import sys
|
|
10
|
+
|
|
11
|
+
sys.dont_write_bytecode = True
|
|
12
|
+
import knowledge
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def git(repo, *args, allow_failure=False):
|
|
16
|
+
env = dict(os.environ, GIT_OPTIONAL_LOCKS='0', GIT_NO_REPLACE_OBJECTS='1',
|
|
17
|
+
GIT_NO_LAZY_FETCH='1', GIT_ALLOW_PROTOCOL='')
|
|
18
|
+
result = subprocess.run(['git', '-C', str(repo), '--no-optional-locks', *args],
|
|
19
|
+
stdout=subprocess.PIPE, stderr=subprocess.PIPE, env=env)
|
|
20
|
+
if result.returncode and not allow_failure:
|
|
21
|
+
raise ValueError('git ' + args[0] + ' failed: ' + result.stderr.decode('utf-8', 'replace').strip())
|
|
22
|
+
return result
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def text(data):
|
|
26
|
+
return os.fsdecode(data)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def classify(path, prefix):
|
|
30
|
+
if not path.startswith(prefix + '/'):
|
|
31
|
+
return None
|
|
32
|
+
rel = path[len(prefix) + 1:]
|
|
33
|
+
parts = PurePosixPath(rel).parts
|
|
34
|
+
if knowledge.credential_path(rel) or any(p in {'.obsidian', '.trash'} for p in parts):
|
|
35
|
+
return None
|
|
36
|
+
if rel in ('.knowledge/review.json', '.knowledge/sources.json'):
|
|
37
|
+
return 'reviewed_state'
|
|
38
|
+
if rel in ('.knowledge/graph.json', 'Map.canvas', 'graph.html'):
|
|
39
|
+
return 'generated_view'
|
|
40
|
+
if rel in ('.knowledge/sync-plan.json', '.knowledge/sync-status.md', '.knowledge/sync.lock', 'sync.html'):
|
|
41
|
+
return 'local_status'
|
|
42
|
+
if rel.endswith('.md') and '.knowledge' not in parts:
|
|
43
|
+
return 'canonical_markdown'
|
|
44
|
+
return None
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def changes(repo, base, commit, prefix):
|
|
48
|
+
raw = git(repo, 'diff', '--no-ext-diff', '--no-textconv', '--name-status', '-z', '-M', base, commit, '--').stdout.split(b'\0')
|
|
49
|
+
rows, i = [], 0
|
|
50
|
+
while i < len(raw) and raw[i]:
|
|
51
|
+
status = text(raw[i]); i += 1
|
|
52
|
+
count = 2 if status[0] in 'RC' else 1
|
|
53
|
+
paths = [text(item) for item in raw[i:i + count]]; i += count
|
|
54
|
+
categories = [classify(path, prefix) for path in paths]
|
|
55
|
+
visible = [(path, category) for path, category in zip(paths, categories) if category]
|
|
56
|
+
if visible:
|
|
57
|
+
rows.append({'status': status, 'paths': [item[0] for item in visible],
|
|
58
|
+
'categories': [item[1] for item in visible]})
|
|
59
|
+
return rows
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def tree(repo, commit, prefix):
|
|
63
|
+
# Read tree metadata only; never treat a Git object as a filesystem path.
|
|
64
|
+
raw = git(repo, '--literal-pathspecs', 'ls-tree', '-r', '-z', commit, '--', prefix).stdout
|
|
65
|
+
result = {}
|
|
66
|
+
for entry in raw.split(b'\0'):
|
|
67
|
+
if not entry:
|
|
68
|
+
continue
|
|
69
|
+
header, name = entry.split(b'\t', 1)
|
|
70
|
+
mode, kind, oid = header.split()
|
|
71
|
+
path = text(name)
|
|
72
|
+
category = classify(path, prefix)
|
|
73
|
+
if category:
|
|
74
|
+
result[path] = {'mode': text(mode), 'kind': text(kind), 'oid': text(oid), 'category': category}
|
|
75
|
+
return result
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def ids(repo, entries):
|
|
79
|
+
result, skipped = {}, []
|
|
80
|
+
for path, item in entries.items():
|
|
81
|
+
if item['category'] != 'canonical_markdown':
|
|
82
|
+
continue
|
|
83
|
+
if item['kind'] != 'blob' or item['mode'] not in ('100644', '100755'):
|
|
84
|
+
skipped.append({'path': path, 'reason': 'not a regular file blob'})
|
|
85
|
+
continue
|
|
86
|
+
blob = git(repo, 'cat-file', 'blob', item['oid']).stdout
|
|
87
|
+
try:
|
|
88
|
+
content = blob.decode('utf-8')
|
|
89
|
+
front = re.match(r'\A---\s*\n(.*?)\n---\s*(?:\n|$)', content, re.S)
|
|
90
|
+
if not front or knowledge.has_conflict_markers(content):
|
|
91
|
+
raise ValueError('missing or conflicted frontmatter')
|
|
92
|
+
matches = re.findall(r'^id:\s*(.*?)\s*$', front.group(1), re.M)
|
|
93
|
+
if len(matches) != 1:
|
|
94
|
+
raise ValueError('missing or duplicate id')
|
|
95
|
+
ident = json.loads(matches[0])
|
|
96
|
+
if not isinstance(ident, str) or not re.fullmatch(r'[a-z0-9-]+', ident):
|
|
97
|
+
raise ValueError('invalid id')
|
|
98
|
+
result.setdefault(ident, []).append(path)
|
|
99
|
+
except (UnicodeDecodeError, ValueError):
|
|
100
|
+
skipped.append({'path': path, 'reason': 'cannot parse a stable id'})
|
|
101
|
+
return result, skipped
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def inspect(repo, vault, ours, theirs):
|
|
105
|
+
if not repo.is_dir() or not vault.is_dir() or not vault.is_relative_to(repo) or repo == vault:
|
|
106
|
+
raise ValueError('repo and vault must be existing directories; vault must be inside repo')
|
|
107
|
+
config = git(repo, 'config', '--get-regexp', r'^(extensions\.partialclone|remote\..*\.promisor)$', allow_failure=True)
|
|
108
|
+
if config.returncode not in (0, 1):
|
|
109
|
+
raise ValueError('cannot inspect Git repository configuration')
|
|
110
|
+
if config.returncode == 0:
|
|
111
|
+
raise ValueError('partial or promisor repository requires full local history')
|
|
112
|
+
top = Path(text(git(repo, 'rev-parse', '--show-toplevel').stdout).strip()).resolve()
|
|
113
|
+
if repo != top:
|
|
114
|
+
raise ValueError('repo must be the worktree root')
|
|
115
|
+
if git(repo, 'rev-parse', '--is-shallow-repository').stdout.strip() == b'true':
|
|
116
|
+
raise ValueError('shallow history cannot establish a reliable merge base')
|
|
117
|
+
# --end-of-options prevents refs from becoming options. Verify explicit commit objects.
|
|
118
|
+
commits = []
|
|
119
|
+
for ref in (ours, theirs):
|
|
120
|
+
if not ref:
|
|
121
|
+
raise ValueError('refs must be nonempty')
|
|
122
|
+
resolved = git(repo, 'rev-parse', '--verify', '--end-of-options', ref + '^{commit}')
|
|
123
|
+
if b'ambiguous' in resolved.stderr.lower():
|
|
124
|
+
raise ValueError('ambiguous ref: ' + ref)
|
|
125
|
+
commits.append(text(resolved.stdout).strip())
|
|
126
|
+
result = git(repo, 'merge-base', '--all', *commits, allow_failure=True)
|
|
127
|
+
bases = text(result.stdout).splitlines()
|
|
128
|
+
if result.returncode or not bases:
|
|
129
|
+
raise ValueError('no common merge base (unrelated histories or invalid history)')
|
|
130
|
+
if len(bases) != 1:
|
|
131
|
+
raise ValueError('multiple merge bases; inspect history manually')
|
|
132
|
+
base, prefix = bases[0], vault.relative_to(repo).as_posix()
|
|
133
|
+
sides = {side: changes(repo, base, commit, prefix) for side, commit in zip(('ours', 'theirs'), commits)}
|
|
134
|
+
trees = {side: tree(repo, commit, prefix) for side, commit in zip(('base', 'ours', 'theirs'), (base, *commits))}
|
|
135
|
+
touched = {side: {path for row in rows for path, category in zip(row['paths'], row['categories']) if category == 'canonical_markdown'} for side, rows in sides.items()}
|
|
136
|
+
our_ids, our_skipped = ids(repo, trees['ours'])
|
|
137
|
+
their_ids, their_skipped = ids(repo, trees['theirs'])
|
|
138
|
+
duplicates = [{'id': ident, 'ours': sorted(our_ids[ident]), 'theirs': sorted(their_ids[ident])}
|
|
139
|
+
for ident in sorted(our_ids.keys() & their_ids.keys())
|
|
140
|
+
if any(a != b for a in our_ids[ident] for b in their_ids[ident])]
|
|
141
|
+
state = {}
|
|
142
|
+
for rel in ('.knowledge/review.json', '.knowledge/sources.json'):
|
|
143
|
+
path = prefix + '/' + rel
|
|
144
|
+
values = {side: trees[side].get(path) for side in ('base', 'ours', 'theirs')}
|
|
145
|
+
state[rel] = {'base': values['base'], 'ours': values['ours'], 'theirs': values['theirs'],
|
|
146
|
+
'different': values['ours'] != values['theirs']}
|
|
147
|
+
unmerged_raw = git(repo, 'ls-files', '-u', '-z').stdout
|
|
148
|
+
unmerged = sorted({text(entry.split(b'\t', 1)[1]) for entry in unmerged_raw.split(b'\0') if entry and b'\t' in entry})
|
|
149
|
+
report = {'base': base, 'ours': commits[0], 'theirs': commits[1], 'changes': sides,
|
|
150
|
+
'shared_canonical_paths': sorted(touched['ours'] & touched['theirs']),
|
|
151
|
+
'duplicate_ids': duplicates, 'reviewed_state': state,
|
|
152
|
+
'unmerged_index_paths': unmerged,
|
|
153
|
+
'skipped_id_paths': {'ours': our_skipped, 'theirs': their_skipped}}
|
|
154
|
+
report['needs_review'] = bool(report['shared_canonical_paths'] or duplicates or unmerged or our_skipped or their_skipped or any(x['different'] for x in state.values()))
|
|
155
|
+
return report
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
def main():
|
|
159
|
+
parser = argparse.ArgumentParser(description=__doc__)
|
|
160
|
+
sub = parser.add_subparsers(dest='command', required=True)
|
|
161
|
+
inspect_parser = sub.add_parser('inspect')
|
|
162
|
+
inspect_parser.add_argument('--repo', required=True, type=Path)
|
|
163
|
+
inspect_parser.add_argument('--vault', required=True, type=Path)
|
|
164
|
+
inspect_parser.add_argument('--ours', required=True)
|
|
165
|
+
inspect_parser.add_argument('--theirs', required=True)
|
|
166
|
+
inspect_parser.add_argument('--json', action='store_true')
|
|
167
|
+
args = parser.parse_args()
|
|
168
|
+
report = inspect(args.repo.resolve(), args.vault.resolve(), args.ours, args.theirs)
|
|
169
|
+
if args.json:
|
|
170
|
+
print(json.dumps(report, ensure_ascii=True, indent=2))
|
|
171
|
+
else:
|
|
172
|
+
print('Needs review:' if report['needs_review'] else 'No overlapping candidates detected:')
|
|
173
|
+
print(json.dumps(report, ensure_ascii=True, indent=2))
|
|
174
|
+
return 0
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
if __name__ == '__main__':
|
|
178
|
+
try:
|
|
179
|
+
sys.exit(main())
|
|
180
|
+
except (OSError, ValueError, KeyError) as exc:
|
|
181
|
+
print('ERROR:', exc, file=sys.stderr)
|
|
182
|
+
sys.exit(1)
|