Skip to content

Commit 0a816f9

Browse files
feat(sleep): stage one proposal and manifest row per skill
Add SkillProposal, skill_proposal_rows, and write_skill_proposals: validate skill names, live target paths, and collisions before writing, then write each skill's proposal atomically. write_staging gains an optional skill_proposals fan-out and keeps the legacy single-proposal layout when it is unused. Refs #120
1 parent 92ec992 commit 0a816f9

2 files changed

Lines changed: 299 additions & 1 deletion

File tree

‎skillopt_sleep/staging.py‎

Lines changed: 130 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,10 @@
1111
import os
1212
import re
1313
import shutil
14+
import tempfile
1415
import time
15-
from typing import Any, List, Optional
16+
from dataclasses import dataclass
17+
from typing import Any, Dict, List, Optional, Sequence
1618

1719
from skillopt_sleep.types import SleepReport
1820

@@ -234,6 +236,124 @@ def redact_secrets(value: Any) -> Any:
234236
return value
235237

236238

239+
class StagingError(ValueError):
240+
"""A proposal could not be staged safely (bad name, bad target, collision)."""
241+
242+
243+
@dataclass
244+
class SkillProposal:
245+
"""One skill's proposed document plus the live file it would replace."""
246+
247+
skill_name: str
248+
proposed_skill: str
249+
live_skill_path: str
250+
251+
252+
def _safe_skill_name(name: object) -> str:
253+
"""Return a skill name usable as a single path segment, else ""."""
254+
if not isinstance(name, str):
255+
return ""
256+
candidate = name.strip()
257+
if not candidate or candidate in {os.curdir, os.pardir}:
258+
return ""
259+
if candidate.startswith("~") or os.path.isabs(candidate):
260+
return ""
261+
if os.path.splitdrive(candidate)[0]:
262+
return ""
263+
separators = {"/", "\\", os.sep, os.altsep or os.sep}
264+
if any(sep in candidate for sep in separators):
265+
return ""
266+
if any(ord(ch) < 32 or ord(ch) == 127 for ch in candidate):
267+
return ""
268+
return candidate
269+
270+
271+
def _safe_live_path(path: object) -> str:
272+
"""Return an absolute, traversal-free ``*.md`` target path, else ""."""
273+
if not isinstance(path, str) or not path.strip():
274+
return ""
275+
candidate = path.strip()
276+
if candidate.startswith("~") or not os.path.isabs(candidate):
277+
return ""
278+
if os.path.normpath(candidate) != candidate:
279+
return ""
280+
if not candidate.endswith(".md"):
281+
return ""
282+
return candidate
283+
284+
285+
def proposal_filename(skill_name: str) -> str:
286+
"""Staged filename for one skill's proposal (unique per skill name)."""
287+
return f"proposed_SKILL.{skill_name}.md"
288+
289+
290+
def _write_atomic(path: str, text: str) -> None:
291+
"""Write ``text`` to ``path`` atomically, so review never sees half a file."""
292+
directory = os.path.dirname(path) or "."
293+
os.makedirs(directory, exist_ok=True)
294+
fd, tmp = tempfile.mkstemp(dir=directory, prefix=".tmp-", suffix=".md")
295+
try:
296+
with os.fdopen(fd, "w", encoding="utf-8") as f:
297+
f.write(text)
298+
f.flush()
299+
os.fsync(f.fileno())
300+
os.replace(tmp, path)
301+
except BaseException:
302+
if os.path.exists(tmp):
303+
os.unlink(tmp)
304+
raise
305+
306+
307+
def skill_proposal_rows(proposals: Sequence[SkillProposal]) -> List[Dict[str, Any]]:
308+
"""Validate proposals and return their manifest rows, in input order.
309+
310+
Raises :class:`StagingError` on an unusable skill name, an unsafe live target
311+
path, or a collision on either the skill name or the live path: a night must
312+
never stage two skills into one file or point a proposal at the wrong one.
313+
"""
314+
rows: List[Dict[str, Any]] = []
315+
seen_paths: Dict[str, str] = {}
316+
for proposal in proposals:
317+
name = _safe_skill_name(proposal.skill_name)
318+
if not name:
319+
raise StagingError(f"unsafe skill name for staging: {proposal.skill_name!r}")
320+
live = _safe_live_path(proposal.live_skill_path)
321+
if not live:
322+
raise StagingError(
323+
f"unsafe live skill path for {name!r}: {proposal.live_skill_path!r}"
324+
)
325+
if any(row["skill_name"] == name for row in rows):
326+
raise StagingError(f"duplicate skill name in staging fan-out: {name!r}")
327+
if live in seen_paths:
328+
raise StagingError(
329+
f"skills {seen_paths[live]!r} and {name!r} target the same file: {live}"
330+
)
331+
seen_paths[live] = name
332+
rows.append({
333+
"skill_name": name,
334+
"proposed_file": proposal_filename(name),
335+
"live_skill_path": live,
336+
})
337+
return rows
338+
339+
340+
def write_skill_proposals(
341+
out_dir: str, proposals: Sequence[SkillProposal]
342+
) -> List[Dict[str, Any]]:
343+
"""Stage one uniquely named proposal file per skill; return manifest rows.
344+
345+
Every proposal is validated before anything is written, so a rejected
346+
fan-out leaves no partial files behind.
347+
"""
348+
rows = skill_proposal_rows(proposals)
349+
if not rows:
350+
return rows
351+
os.makedirs(out_dir, exist_ok=True)
352+
for row, proposal in zip(rows, proposals):
353+
_write_atomic(os.path.join(out_dir, row["proposed_file"]), proposal.proposed_skill)
354+
return rows
355+
356+
237357
def _ts_dir() -> str:
238358
return time.strftime("%Y%m%d-%H%M%S", time.localtime())
239359

@@ -279,23 +399,32 @@ def write_staging(
279399
live_memory_path: str,
280400
report_md: str,
281401
out_dir: str = "",
402+
skill_proposals: Sequence[SkillProposal] = (),
282403
) -> str:
283404
"""Write proposals + report into staging/<ts>/ and return that path.
284405
285406
``out_dir`` lets the cycle pre-create the night's staging folder at cycle
286407
START, so incremental artifacts (evidence.jsonl) accumulate in the same
287408
place the report lands.
409+
410+
``skill_proposals`` stages one extra uniquely named file and manifest row per
411+
skill for a multi-skill night. Left empty, the staging layout and manifest
412+
are exactly the legacy single-proposal ones.
288413
"""
289414
out = out_dir or os.path.join(staging_root(project), _ts_dir())
290415
os.makedirs(out, exist_ok=True)
291416

417+
skill_rows = write_skill_proposals(out, skill_proposals)
418+
292419
manifest = {
293420
"live_skill_path": live_skill_path,
294421
"live_memory_path": live_memory_path,
295422
"has_skill": proposed_skill is not None,
296423
"has_memory": proposed_memory is not None,
297424
"accepted": report.accepted,
298425
}
426+
if skill_rows:
427+
manifest["skills"] = skill_rows
299428
if proposed_skill is not None:
300429
with open(os.path.join(out, "proposed_SKILL.md"), "w", encoding="utf-8") as f:
301430
f.write(proposed_skill)

‎tests/test_sleep_staging_fanout.py‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
"""Tests for per-skill staging fan-out (issue #120).
2+
3+
Pure-stdlib (unittest), hermetic (tmpdir only), no API key, no network.
4+
Run: python -m pytest tests/test_sleep_staging_fanout.py
5+
"""
6+
from __future__ import annotations
7+
8+
import json
9+
import os
10+
import tempfile
11+
import unittest
12+
13+
from skillopt_sleep.staging import (
14+
SkillProposal,
15+
StagingError,
16+
proposal_filename,
17+
skill_proposal_rows,
18+
write_skill_proposals,
19+
write_staging,
20+
)
21+
from skillopt_sleep.types import SleepReport
22+
23+
24+
def _proposal(name="example-skill", body="# example\n", live=None, root="/tmp/live"):
25+
if live is None:
26+
live = os.path.join(root, name, "SKILL.md")
27+
return SkillProposal(name, body, live)
28+
29+
30+
def _report():
31+
return SleepReport(night=1, project="/repo/example", accepted=True,
32+
gate_action="accept_new_best")
33+
34+
35+
class TestSkillProposalRows(unittest.TestCase):
36+
def test_one_row_per_skill_in_order(self):
37+
rows = skill_proposal_rows([_proposal("alpha"), _proposal("beta")])
38+
self.assertEqual([r["skill_name"] for r in rows], ["alpha", "beta"])
39+
self.assertEqual([r["proposed_file"] for r in rows],
40+
["proposed_SKILL.alpha.md", "proposed_SKILL.beta.md"])
41+
self.assertEqual(rows[0]["live_skill_path"], "/tmp/live/alpha/SKILL.md")
42+
43+
def test_filenames_are_unique_per_skill(self):
44+
self.assertNotEqual(proposal_filename("alpha"), proposal_filename("beta"))
45+
46+
def test_duplicate_skill_name_is_refused(self):
47+
with self.assertRaises(StagingError):
48+
skill_proposal_rows([_proposal("alpha"),
49+
_proposal("alpha", live="/tmp/other/SKILL.md")])
50+
51+
def test_two_skills_targeting_one_file_are_refused(self):
52+
shared = "/tmp/live/shared/SKILL.md"
53+
with self.assertRaises(StagingError):
54+
skill_proposal_rows([_proposal("alpha", live=shared),
55+
_proposal("beta", live=shared)])
56+
57+
def test_unsafe_skill_names_are_refused(self):
58+
for bad in ["", " ", ".", "..", "../escape", "a/b", "a\\b", "/abs",
59+
"~home", "bad\nname"]:
60+
with self.assertRaises(StagingError, msg=bad):
61+
skill_proposal_rows([_proposal(bad)])
62+
63+
def test_unsafe_live_paths_are_refused(self):
64+
for bad in ["", "relative/SKILL.md", "~/skills/a/SKILL.md",
65+
"/tmp/live/../../etc/SKILL.md", "/tmp/live/a/SKILL.txt"]:
66+
with self.assertRaises(StagingError, msg=bad):
67+
skill_proposal_rows([_proposal("alpha", live=bad)])
68+
69+
70+
class TestWriteSkillProposals(unittest.TestCase):
71+
def test_writes_one_file_per_skill(self):
72+
with tempfile.TemporaryDirectory() as tmp:
73+
rows = write_skill_proposals(tmp, [
74+
_proposal("alpha", "# alpha\n"),
75+
_proposal("beta", "# beta\n"),
76+
])
77+
self.assertEqual(sorted(os.listdir(tmp)),
78+
["proposed_SKILL.alpha.md", "proposed_SKILL.beta.md"])
79+
with open(os.path.join(tmp, rows[0]["proposed_file"]), encoding="utf-8") as f:
80+
self.assertEqual(f.read(), "# alpha\n")
81+
82+
def test_no_proposals_writes_nothing(self):
83+
with tempfile.TemporaryDirectory() as tmp:
84+
self.assertEqual(write_skill_proposals(tmp, []), [])
85+
self.assertEqual(os.listdir(tmp), [])
86+
87+
def test_rejected_fan_out_leaves_no_partial_files(self):
88+
with tempfile.TemporaryDirectory() as tmp:
89+
with self.assertRaises(StagingError):
90+
write_skill_proposals(tmp, [_proposal("alpha"), _proposal("../escape")])
91+
self.assertEqual(os.listdir(tmp), [])
92+
93+
def test_writes_leave_no_temporary_files_behind(self):
94+
with tempfile.TemporaryDirectory() as tmp:
95+
write_skill_proposals(tmp, [_proposal("alpha")])
96+
self.assertEqual([n for n in os.listdir(tmp) if n.startswith(".tmp-")], [])
97+
98+
def test_rewrite_replaces_content_atomically(self):
99+
with tempfile.TemporaryDirectory() as tmp:
100+
write_skill_proposals(tmp, [_proposal("alpha", "# first\n")])
101+
write_skill_proposals(tmp, [_proposal("alpha", "# second\n")])
102+
path = os.path.join(tmp, proposal_filename("alpha"))
103+
with open(path, encoding="utf-8") as f:
104+
self.assertEqual(f.read(), "# second\n")
105+
self.assertEqual(sorted(os.listdir(tmp)), [proposal_filename("alpha")])
106+
107+
108+
class TestWriteStagingCompatibility(unittest.TestCase):
109+
def _manifest(self, out):
110+
with open(os.path.join(out, "manifest.json"), encoding="utf-8") as f:
111+
return json.load(f)
112+
113+
def test_legacy_layout_when_multi_skill_is_unused(self):
114+
with tempfile.TemporaryDirectory() as tmp:
115+
out = write_staging(
116+
tmp, report=_report(), proposed_skill="# skill\n",
117+
proposed_memory="# memory\n",
118+
live_skill_path=os.path.join(tmp, "live", "SKILL.md"),
119+
live_memory_path=os.path.join(tmp, "live", "CLAUDE.md"),
120+
report_md="# report\n",
121+
)
122+
self.assertEqual(
123+
sorted(os.listdir(out)),
124+
["manifest.json", "proposed_CLAUDE.md", "proposed_SKILL.md",
125+
"report.json", "report.md"],
126+
)
127+
manifest = self._manifest(out)
128+
self.assertNotIn("skills", manifest)
129+
self.assertTrue(manifest["has_skill"])
130+
131+
def test_fan_out_adds_files_and_manifest_rows(self):
132+
with tempfile.TemporaryDirectory() as tmp:
133+
live_root = os.path.join(tmp, "live")
134+
out = write_staging(
135+
tmp, report=_report(), proposed_skill=None, proposed_memory=None,
136+
live_skill_path=os.path.join(live_root, "SKILL.md"),
137+
live_memory_path=os.path.join(live_root, "CLAUDE.md"),
138+
report_md="# report\n",
139+
skill_proposals=[
140+
_proposal("alpha", "# alpha\n", root=live_root),
141+
_proposal("beta", "# beta\n", root=live_root),
142+
],
143+
)
144+
self.assertEqual(
145+
sorted(os.listdir(out)),
146+
["manifest.json", "proposed_SKILL.alpha.md", "proposed_SKILL.beta.md",
147+
"report.json", "report.md"],
148+
)
149+
rows = self._manifest(out)["skills"]
150+
self.assertEqual([r["skill_name"] for r in rows], ["alpha", "beta"])
151+
self.assertEqual(rows[1]["live_skill_path"],
152+
os.path.join(live_root, "beta", "SKILL.md"))
153+
154+
def test_unsafe_fan_out_writes_no_manifest(self):
155+
with tempfile.TemporaryDirectory() as tmp:
156+
with self.assertRaises(StagingError):
157+
write_staging(
158+
tmp, report=_report(), proposed_skill=None, proposed_memory=None,
159+
live_skill_path=os.path.join(tmp, "live", "SKILL.md"),
160+
live_memory_path=os.path.join(tmp, "live", "CLAUDE.md"),
161+
report_md="# report\n",
162+
skill_proposals=[_proposal("alpha", live="relative/SKILL.md")],
163+
)
164+
for root, _dirs, files in os.walk(tmp):
165+
self.assertNotIn("manifest.json", files, root)
166+
167+
168+
if __name__ == "__main__":
169+
unittest.main()

0 commit comments

Comments
 (0)