Free, open source blog writer for Claude Code. Researches current sources, writes answer-first posts for Google and AI answers, has an independent reviewer score each one out of 100 and ships only after five delivery gates. 32 skills, 30 /blog commands, 5 agents. Active development at AI-Marketing-Hub/claude-blog; public releases ship here.
Python agent-skillsaiai-citationsai-contentai-marketingai-marketing-hubblogblog-writingclaude-codeclaude-code-skillclaude-pluginclaude-skillcontent-creationcontent-optimizationcontent-strategyeeatgeomultilingualopen-sourceseo
#!/usr/bin/env python3
"""Shared ownership engine for the Unix installer and uninstaller.
The engine treats both the v2 per-file manifest and the reviewed legacy
inventory as ownership proofs. It preflights the complete operation before
moving any file, uses no-follow directory descriptors for profile mutations,
and replaces the manifest only after the payload is complete.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import os
import re
import shutil
import stat
import sys
import tempfile
import time
from dataclasses import dataclass
from pathlib import Path, PurePosixPath
OWNER = "claude-blog-unix-installer"
LEGACY_OWNER = "claude-blog-reviewed-legacy-payload"
HEX64 = re.compile(r"[0-9a-f]{64}")
BACKUP_DIRECTORY = "claude-blog-backups"
MODIFIED_LIST_LIMIT = 10
class DuplicateJSONKey(ValueError):
pass
def fail(message: str) -> None:
raise SystemExit(f"ERROR: {message}")
def unique_object(pairs: list[tuple[str, object]]) -> dict[str, object]:
result: dict[str, object] = {}
for key, value in pairs:
if key in result:
raise DuplicateJSONKey(key)
result[key] = value
return result
def allowed_relative(relative: PurePosixPath) -> bool:
parts = relative.parts
if not parts or relative.is_absolute() or ".." in parts or "." in parts:
return False
if len(parts) >= 3 and parts[0] == "skills":
return parts[1] == "blog" or parts[1].startswith("blog-")
if len(parts) == 2 and parts[0] == "agents":
return parts[1].startswith("blog-") and parts[1].endswith(".md")
return len(parts) == 2 and parts[0] == "scripts" and parts[1].endswith(".py")
def _lstat_component(dir_fd: int, name: str) -> os.stat_result | None:
"""lstat one directory entry relative to an open directory, or None."""
try:
return os.stat(name, dir_fd=dir_fd, follow_symlinks=False)
except OSError:
return None
def is_trusted_system_symlink(path: Path, link_stat: os.stat_result) -> bool:
"""True for an OS-level alias such as /home -> var/home.
Same rule as scripts/blog_render.py (_is_trusted_system_symlink): only a
root-owned link sitting directly under the filesystem root qualifies, and
a user cannot create one there.
"""
if os.name != "posix" or not hasattr(link_stat, "st_uid"):
return False
return link_stat.st_uid == 0 and path.parent == Path(path.anchor)
@dataclass(frozen=True)
class Incoming:
source: Path
mode: int
class ProfileFS:
"""No-follow file operations rooted at one Claude profile directory."""
def __init__(self, root: Path):
self.root = root.absolute()
current_path = Path(self.root.anchor)
current = os.open(
current_path,
os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0),
)
last = len(self.root.parts) - 2
try:
for index, part in enumerate(self.root.parts[1:]):
current_path /= part
try:
following = os.open(
part,
os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0),
dir_fd=current,
)
except FileNotFoundError:
os.mkdir(part, 0o755, dir_fd=current)
following = os.open(
part,
os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0),
dir_fd=current,
)
except OSError as exc:
link_stat = _lstat_component(current, part)
if link_stat is None or not stat.S_ISLNK(link_stat.st_mode):
fail(f"Claude profile path has an unsafe ancestor at {current_path}: {exc.strerror}")
# A root-owned alias directly under the filesystem root
# (Aurora and Silverblue: /home -> var/home) is honoured for
# ancestors. The profile directory itself, and any link a
# user could have created, is refused.
if index == last or not is_trusted_system_symlink(current_path, link_stat):
fail(f"refusing symlinked path component {current_path}")
try:
following = os.open(part, os.O_RDONLY | os.O_DIRECTORY, dir_fd=current)
except OSError as inner:
fail(f"Claude profile path has an unsafe ancestor at {current_path}: {inner.strerror}")
os.close(current)
current = following
finally:
os.close(current)
def relative(self, path: Path) -> PurePosixPath:
raw = str(path)
if not path.is_absolute() or ".." in Path(raw).parts:
fail(f"unsafe path: {path}")
try:
value = path.relative_to(self.root)
except ValueError:
fail(f"unsafe path outside Claude profile: {path}")
relative = PurePosixPath(*value.parts)
if not allowed_relative(relative):
fail(f"unsafe path: {path}")
return relative
def absolute(self, relative: PurePosixPath) -> Path:
if not allowed_relative(relative):
fail(f"unsafe relative installation path: {relative}")
return self.root.joinpath(*relative.parts)
def _root_fd(self) -> int:
return os.open(
self.root,
os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0),
)
def root_status(self, name: str) -> os.stat_result | None:
root = self._root_fd()
try:
try:
return os.stat(name, dir_fd=root, follow_symlinks=False)
except FileNotFoundError:
return None
finally:
os.close(root)
def read_root_file(self, name: str) -> bytes:
root = self._root_fd()
try:
fd = os.open(name, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0), dir_fd=root)
try:
if not stat.S_ISREG(os.fstat(fd).st_mode):
fail(f"profile metadata is not a regular file: {self.root / name}")
chunks: list[bytes] = []
while chunk := os.read(fd, 1024 * 1024):
chunks.append(chunk)
return b"".join(chunks)
finally:
os.close(fd)
finally:
os.close(root)
def write_root_file(self, name: str, payload: bytes, mode: int) -> None:
root = self._root_fd()
temporary = f".{name}.claude-blog-{os.getpid()}"
fd = -1
try:
fd = os.open(
temporary,
os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
mode,
dir_fd=root,
)
remaining = memoryview(payload)
while remaining:
written = os.write(fd, remaining)
remaining = remaining[written:]
os.fchmod(fd, mode)
os.close(fd)
fd = -1
os.rename(temporary, name, src_dir_fd=root, dst_dir_fd=root)
finally:
if fd >= 0:
os.close(fd)
try:
os.unlink(temporary, dir_fd=root)
except FileNotFoundError:
pass
os.close(root)
def unlink_root_file(self, name: str) -> None:
root = self._root_fd()
try:
os.unlink(name, dir_fd=root)
finally:
os.close(root)
def parent_fd(self, relative: PurePosixPath, *, create: bool = False) -> int:
if not allowed_relative(relative):
fail(f"unsafe relative installation path: {relative}")
current = self._root_fd()
try:
for part in relative.parts[:-1]:
try:
following = os.open(
part,
os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0),
dir_fd=current,
)
except FileNotFoundError:
if not create:
raise
os.mkdir(part, 0o755, dir_fd=current)
following = os.open(
part,
os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0),
dir_fd=current,
)
except OSError as exc:
link_stat = _lstat_component(current, part)
if link_stat is not None and stat.S_ISLNK(link_stat.st_mode):
fail(f"refusing symlinked path component {self.root.joinpath(*relative.parts[: relative.parts.index(part) + 1])}")
fail(f"installation path has an unsafe parent at {part}: {exc.strerror}")
os.close(current)
current = following
return current
except BaseException:
os.close(current)
raise
def status(self, relative: PurePosixPath) -> os.stat_result | None:
try:
parent = self.parent_fd(relative)
except FileNotFoundError:
return None
try:
try:
return os.stat(relative.name, dir_fd=parent, follow_symlinks=False)
except FileNotFoundError:
return None
finally:
os.close(parent)
def hash(self, relative: PurePosixPath) -> str:
parent = self.parent_fd(relative)
try:
flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
fd = os.open(relative.name, flags, dir_fd=parent)
try:
if not stat.S_ISREG(os.fstat(fd).st_mode):
fail(f"managed installation path is not a regular file: {self.absolute(relative)}")
value = hashlib.sha256()
while chunk := os.read(fd, 1024 * 1024):
value.update(chunk)
return value.hexdigest()
finally:
os.close(fd)
finally:
os.close(parent)
def write(self, relative: PurePosixPath, source: Path, mode: int) -> None:
parent = self.parent_fd(relative, create=True)
temporary = f".{relative.name}.claude-blog-{os.getpid()}"
source_fd = os.open(source, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
target_fd = -1
try:
if not stat.S_ISREG(os.fstat(source_fd).st_mode):
fail(f"source payload is not a regular file: {source}")
target_fd = os.open(
temporary,
os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
mode,
dir_fd=parent,
)
while chunk := os.read(source_fd, 1024 * 1024):
remaining = memoryview(chunk)
while remaining:
written = os.write(target_fd, remaining)
remaining = remaining[written:]
os.fchmod(target_fd, mode)
os.close(target_fd)
target_fd = -1
os.rename(temporary, relative.name, src_dir_fd=parent, dst_dir_fd=parent)
finally:
if target_fd >= 0:
os.close(target_fd)
os.close(source_fd)
try:
os.unlink(temporary, dir_fd=parent)
except FileNotFoundError:
pass
os.close(parent)
def backup(self, relative: PurePosixPath, label: str) -> Path:
"""Copy one regular file to <profile>/claude-blog-backups/<label>/<relative>.
Every directory is opened without following symlinks and the copy is
created exclusively, so a backup can never write through a link.
"""
parent = self.parent_fd(relative)
try:
source_fd = os.open(relative.name, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0), dir_fd=parent)
finally:
os.close(parent)
try:
if not stat.S_ISREG(os.fstat(source_fd).st_mode):
fail(f"cannot back up a path that is not a regular file: {self.absolute(relative)}")
current = self._root_fd()
try:
for part in (BACKUP_DIRECTORY, label, *relative.parts[:-1]):
try:
os.mkdir(part, 0o700, dir_fd=current)
except FileExistsError:
pass
following = os.open(
part,
os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0),
dir_fd=current,
)
os.close(current)
current = following
target_fd = os.open(
relative.name,
os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
0o600,
dir_fd=current,
)
try:
while chunk := os.read(source_fd, 1024 * 1024):
remaining = memoryview(chunk)
while remaining:
written = os.write(target_fd, remaining)
remaining = remaining[written:]
finally:
os.close(target_fd)
except OSError as exc:
fail(f"could not back up {self.absolute(relative)}: {exc.strerror}")
finally:
os.close(current)
finally:
os.close(source_fd)
return self.root.joinpath(BACKUP_DIRECTORY, label, *relative.parts)
def unlink(self, relative: PurePosixPath) -> None:
parent = self.parent_fd(relative)
try:
os.unlink(relative.name, dir_fd=parent)
finally:
os.close(parent)
def prune(self, relative: PurePosixPath) -> None:
parts = list(relative.parts[:-1])
while parts:
parent_parts = parts[:-1]
name = parts[-1]
current = self._root_fd()
try:
safe = True
for part in parent_parts:
try:
following = os.open(
part,
os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0),
dir_fd=current,
)
except OSError:
safe = False
break
os.close(current)
current = following
if not safe:
return
try:
os.rmdir(name, dir_fd=current)
except OSError:
return
finally:
os.close(current)
parts.pop()
class Transaction:
def __init__(self, fs: ProfileFS):
self.fs = fs
self.directory = Path(tempfile.mkdtemp(prefix=".claude-blog-transaction-", dir=fs.root))
self.directory.chmod(0o700)
self.staged: list[tuple[PurePosixPath, Path]] = []
self.written: list[PurePosixPath] = []
self.committed = False
def stage(self, relative: PurePosixPath) -> None:
status = self.fs.status(relative)
if status is None:
return
if not stat.S_ISREG(status.st_mode):
fail(f"managed installation path is not a regular file: {self.fs.absolute(relative)}")
parent = self.fs.parent_fd(relative)
staged = self.directory / f"{len(self.staged):06d}"
stage_fd = os.open(
self.directory,
os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0),
)
try:
os.rename(relative.name, staged.name, src_dir_fd=parent, dst_dir_fd=stage_fd)
finally:
os.close(stage_fd)
os.close(parent)
self.staged.append((relative, staged))
def write(self, relative: PurePosixPath, incoming: Incoming) -> None:
self.fs.write(relative, incoming.source, incoming.mode)
self.written.append(relative)
def rollback(self) -> None:
if self.committed:
return
for relative in reversed(self.written):
try:
if self.fs.status(relative) is not None:
self.fs.unlink(relative)
except OSError:
pass
for relative, staged in reversed(self.staged):
if not staged.exists():
continue
parent = self.fs.parent_fd(relative, create=True)
stage_fd = os.open(self.directory, os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0))
try:
os.rename(staged.name, relative.name, src_dir_fd=stage_fd, dst_dir_fd=parent)
finally:
os.close(stage_fd)
os.close(parent)
def finish(self) -> None:
self.committed = True
shutil.rmtree(self.directory, ignore_errors=True)
def close(self) -> None:
if not self.committed:
self.rollback()
shutil.rmtree(self.directory, ignore_errors=True)
def add_file(incoming: dict[PurePosixPath, Incoming], source: Path, relative: str, *, executable: bool = False) -> None:
key = PurePosixPath(relative)
if not allowed_relative(key) or key in incoming:
fail(f"invalid or duplicate installation destination: {relative}")
if source.is_symlink() or not source.is_file():
fail(f"source payload is not a regular file: {source}")
mode = stat.S_IMODE(source.stat().st_mode)
if executable:
mode |= stat.S_IXUSR
incoming[key] = Incoming(source, mode)
def add_tree(incoming: dict[PurePosixPath, Incoming], source: Path, prefix: str, *, executable_python: bool = False) -> None:
if not source.exists():
return
if source.is_symlink() or not source.is_dir():
fail(f"source payload directory is unsafe: {source}")
for path in sorted(source.rglob("*")):
if path.is_symlink():
fail(f"source payload contains a symlink: {path}")
if not path.is_file() or "__pycache__" in path.parts or path.suffix == ".pyc":
continue
relative = PurePosixPath(prefix) / PurePosixPath(*path.relative_to(source).parts)
add_file(incoming, path, str(relative), executable=executable_python and path.suffix == ".py")
def build_inventory(source: Path) -> tuple[dict[PurePosixPath, Incoming], list[str], list[str], list[str]]:
incoming: dict[PurePosixPath, Incoming] = {}
skills: list[str] = []
agents: list[str] = []
scripts: list[str] = []
blog = source / "skills/blog"
add_file(incoming, blog / "SKILL.md", "skills/blog/SKILL.md")
add_tree(incoming, blog / "references", "skills/blog/references")
add_tree(incoming, blog / "templates", "skills/blog/templates")
ledger = source / "data/google-updates.json"
if ledger.is_file():
add_file(incoming, ledger, "skills/blog/data/google-updates.json")
for skill_dir in sorted((source / "skills").iterdir()):
if not skill_dir.is_dir() or skill_dir.name == "blog":
continue
if skill_dir.is_symlink() or not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", skill_dir.name):
fail(f"unsafe source skill directory: {skill_dir}")
skill_md = skill_dir / "SKILL.md"
if not skill_md.is_file():
continue
skills.append(skill_dir.name)
add_file(incoming, skill_md, f"skills/{skill_dir.name}/SKILL.md")
for payload in ("references", "scripts", "assets", "templates"):
add_tree(
incoming,
skill_dir / payload,
f"skills/{skill_dir.name}/{payload}",
executable_python=payload == "scripts",
)
for agent in sorted((source / "agents").glob("*.md")):
agents.append(agent.name)
add_file(incoming, agent, f"agents/{agent.name}")
# Public installer contract: scripts/*.py
for script in sorted((source / "scripts").glob("*.py")):
scripts.append(script.name)
add_file(incoming, script, f"scripts/{script.name}", executable=True)
if script.name == "analyze_blog.py":
add_file(incoming, script, "skills/blog/scripts/analyze_blog.py", executable=True)
return incoming, skills, agents, scripts
def load_legacy_inventory(path: Path) -> dict[PurePosixPath, set[str]]:
if path.is_symlink() or not path.is_file():
fail(f"reviewed legacy ownership inventory is unavailable: {path}")
try:
data = json.loads(path.read_bytes(), object_pairs_hook=unique_object)
except DuplicateJSONKey as exc:
fail(f"reviewed legacy ownership inventory has a duplicate key: {exc}")
except (UnicodeDecodeError, ValueError):
fail(f"reviewed legacy ownership inventory is invalid: {path}")
if data.get("schema_version") != 1 or data.get("owner") != LEGACY_OWNER or not isinstance(data.get("files"), dict):
fail(f"reviewed legacy ownership inventory has an unsupported schema: {path}")
result: dict[PurePosixPath, set[str]] = {}
for raw, records in data["files"].items():
relative = PurePosixPath(raw)
if relative in result or not allowed_relative(relative) or not isinstance(records, list) or not records:
fail(f"reviewed legacy ownership inventory contains an unsafe path: {raw}")
if any(
not isinstance(record, dict)
or not isinstance(record.get("sha256"), str)
or not HEX64.fullmatch(record["sha256"])
for record in records
):
fail(f"reviewed legacy ownership inventory has an invalid record for: {raw}")
hashes = {record["sha256"] for record in records}
if not hashes:
fail(f"reviewed legacy ownership inventory has no valid hash for: {raw}")
result[relative] = hashes
return result
def load_v2(fs: ProfileFS, manifest: Path) -> tuple[dict[PurePosixPath, str] | None, bytes]:
status = fs.root_status(manifest.name)
if status is None:
return None, b""
if not stat.S_ISREG(status.st_mode):
fail(f"installation manifest is not a regular file: {manifest}")
raw = fs.read_root_file(manifest.name)
try:
data = json.loads(raw, object_pairs_hook=unique_object)
except DuplicateJSONKey as exc:
fail(f"installation manifest has a duplicate key: {exc}")
except (UnicodeDecodeError, ValueError):
return None, raw
if data.get("schema_version") != 2 or data.get("owner") != OWNER or not isinstance(data.get("files"), dict):
fail(f"unrecognized installation manifest: {manifest}")
managed: dict[PurePosixPath, str] = {}
for raw_path, record in data["files"].items():
path = Path(raw_path)
relative = fs.relative(path)
if relative in managed:
fail(f"installation manifest contains a duplicate path: {raw_path}")
if not isinstance(record, dict) or not isinstance(record.get("sha256"), str) or not HEX64.fullmatch(record["sha256"]):
fail(f"installation manifest has an invalid record: {raw_path}")
managed[relative] = record["sha256"]
return managed, raw
def legacy_scopes(fs: ProfileFS, raw: bytes, known: dict[PurePosixPath, set[str]]) -> list[PurePosixPath]:
try:
values = raw.decode("utf-8").splitlines()
except UnicodeDecodeError:
fail("legacy installation manifest is not UTF-8")
scopes: list[PurePosixPath] = []
known_skill_dirs = {PurePosixPath(*path.parts[:2]) for path in known if path.parts[0] == "skills"}
for value in values:
if not value:
continue
path = Path(value)
if not path.is_absolute() or ".." in path.parts:
fail(f"legacy installation manifest contains an unsafe path: {value}")
try:
relative = PurePosixPath(*path.relative_to(fs.root).parts)
except ValueError:
fail(f"legacy installation manifest contains an unsafe path: {value}")
if relative in known_skill_dirs or relative in known:
scopes.append(relative)
else:
fail(f"legacy installation manifest contains an unreviewed scope: {value}")
if not scopes:
fail("legacy installation manifest has no reviewed ownership scopes")
return scopes
def covered(path: PurePosixPath, scopes: list[PurePosixPath]) -> bool:
return any(path == scope or (len(scope.parts) == 2 and scope.parts[0] == "skills" and path.parts[:2] == scope.parts) for scope in scopes)
def modified_files_error(fs: ProfileFS, modified: list[PurePosixPath], operation: str, headline: str) -> None:
shown = modified[:MODIFIED_LIST_LIMIT]
lines = [f"{headline}: {fs.absolute(relative)}" for relative in shown]
if len(modified) > len(shown):
lines.append(f"... and {len(modified) - len(shown)} more modified file(s)")
script = "install.sh" if operation == "install" else "uninstall.sh"
action = "replaced with the packaged version" if operation == "install" else "removed"
lines += [
"",
f"Nothing was changed. {len(modified)} installed file(s) differ from what the installer wrote,",
"so the installer will not overwrite or delete them without your say-so.",
"Safe steps:",
" 1. Copy any edit you want to keep to a location outside ~/.claude/skills, ~/.claude/agents",
" and ~/.claude/scripts.",
f" 2. Run: bash {script} --force-adopt",
f" Each modified file is first copied to {fs.root / BACKUP_DIRECTORY}/<timestamp>/ and then {action}.",
" 3. Re-apply your edits from the backup if you still want them.",
"Alternatively restore the original file contents and run the same command again.",
]
fail("\n".join(lines))
def preflight_v2(
fs: ProfileFS, managed: dict[PurePosixPath, str], force: bool = False,
) -> tuple[list[PurePosixPath], set[PurePosixPath]]:
"""Return (modified, missing). Missing files are only tolerated when forced."""
modified: list[PurePosixPath] = []
missing: set[PurePosixPath] = set()
for relative, expected in managed.items():
status = fs.status(relative)
if status is None and force:
missing.add(relative)
continue
if status is None or not stat.S_ISREG(status.st_mode):
fail(f"managed installation file is missing or replaced: {fs.absolute(relative)}")
if fs.hash(relative) != expected:
modified.append(relative)
return sorted(modified, key=str), missing
def preflight_legacy(
fs: ProfileFS, known: dict[PurePosixPath, set[str]], scopes: list[PurePosixPath],
) -> tuple[set[PurePosixPath], list[PurePosixPath]]:
"""Return (owned, modified). Modified files are in the owned set only for forced runs."""
owned: set[PurePosixPath] = set()
modified: list[PurePosixPath] = []
for relative, hashes in known.items():
if not covered(relative, scopes):
continue
status = fs.status(relative)
if status is None:
continue
if not stat.S_ISREG(status.st_mode):
fail(f"reviewed legacy path is missing or replaced: {fs.absolute(relative)}")
if fs.hash(relative) not in hashes:
modified.append(relative)
owned.add(relative)
return owned, sorted(modified, key=str)
def resolve_ownership(
fs: ProfileFS,
managed: dict[PurePosixPath, str] | None,
raw_manifest: bytes,
legacy_inventory: str | None,
operation: str,
force: bool,
) -> tuple[set[PurePosixPath], list[PurePosixPath]]:
"""Return (owned, modified) after refusing unsafe or unauthorized states."""
if managed is not None:
modified, missing = preflight_v2(fs, managed, force)
owned = set(managed) - missing
headline = "managed installation file was modified"
else:
if not legacy_inventory:
fail("legacy uninstall requires the complete reviewed repository and ownership inventory")
known = load_legacy_inventory(Path(legacy_inventory))
scopes = legacy_scopes(fs, raw_manifest, known)
owned, modified = preflight_legacy(fs, known, scopes)
headline = "reviewed legacy file was modified or is unknown"
if modified and not force:
modified_files_error(fs, modified, operation, headline)
return owned, modified
def back_up_modified(fs: ProfileFS, modified: list[PurePosixPath]) -> None:
if not modified:
return
label = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime()) + f"-{os.getpid()}"
for relative in modified:
copy = fs.backup(relative, label)
print(f" Backed up modified file: {fs.absolute(relative)} -> {copy}")
def validate_manifest_path(fs: ProfileFS, manifest: Path) -> None:
if manifest.parent != fs.root or manifest.name != "claude-blog-manifest.txt":
fail(f"unsafe manifest path: {manifest}")
def stage_manifest(transaction: Transaction, fs: ProfileFS, manifest: Path) -> Path:
status = fs.root_status(manifest.name)
if status is None or not stat.S_ISREG(status.st_mode):
fail(f"installation manifest is not a regular file: {manifest}")
staged = transaction.directory / "manifest"
root = fs._root_fd()
stage = os.open(
transaction.directory,
os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0),
)
try:
os.rename(manifest.name, staged.name, src_dir_fd=root, dst_dir_fd=stage)
finally:
os.close(stage)
os.close(root)
return staged
def restore_manifest(fs: ProfileFS, manifest: Path, staged: Path) -> None:
if staged.exists():
root = fs._root_fd()
stage = os.open(
staged.parent,
os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0),
)
try:
os.rename(staged.name, manifest.name, src_dir_fd=stage, dst_dir_fd=root)
finally:
os.close(stage)
os.close(root)
def write_manifest(manifest: Path, version: str, fs: ProfileFS, incoming: dict[PurePosixPath, Incoming]) -> None:
records = {
str(fs.absolute(relative)): {"sha256": fs.hash(relative), "mode": incoming[relative].mode}
for relative in sorted(incoming, key=str)
}
payload = (json.dumps({
"schema_version": 2,
"owner": OWNER,
"version": version,
"files": records,
}, indent=2, sort_keys=True) + "\n").encode()
fs.write_root_file(manifest.name, payload, 0o600)
def install(args: argparse.Namespace) -> None:
source = Path(args.source).resolve()
fs = ProfileFS(Path(args.profile))
manifest = Path(args.manifest)
validate_manifest_path(fs, manifest)
incoming, skill_names, agent_names, script_names = build_inventory(source)
managed, raw_manifest = load_v2(fs, manifest)
modified: list[PurePosixPath] = []
if managed is not None or raw_manifest:
owned, modified = resolve_ownership(
fs, managed, raw_manifest, args.legacy_inventory, "install", getattr(args, "force_adopt", False),
)
else:
owned = set()
for relative in incoming:
status = fs.status(relative)
if status is not None and relative not in owned:
fail(
f"refusing to overwrite an unowned existing file: {fs.absolute(relative)}\n"
"It is not recorded in the installation manifest. Move or rename it (or delete it if it "
"is disposable) and run the installer again."
)
back_up_modified(fs, modified)
transaction = Transaction(fs)
staged_manifest: Path | None = None
try:
for relative in sorted(owned, key=str):
transaction.stage(relative)
if raw_manifest:
staged_manifest = stage_manifest(transaction, fs, manifest)
for relative, item in incoming.items():
transaction.write(relative, item)
write_manifest(manifest, args.version, fs, incoming)
transaction.finish()
except BaseException:
if fs.root_status(manifest.name) is not None and staged_manifest is not None:
fs.unlink_root_file(manifest.name)
if staged_manifest is not None:
restore_manifest(fs, manifest, staged_manifest)
transaction.close()
raise
for relative in sorted(owned - set(incoming), key=lambda value: len(value.parts), reverse=True):
fs.prune(relative)
Path(args.stats).write_text(json.dumps({
"sub_skill_count": len(skill_names),
"agent_count": len(agent_names),
"root_script_count": len(script_names),
}) + "\n", encoding="utf-8")
print("→ Creating directories...")
print("→ Installing main skill: blog...")
print("→ Installing reference files...")
if (source / "skills/blog/templates").is_dir():
print("→ Installing content templates...")
if (source / "data/google-updates.json").is_file():
print("→ Installing Google update ledger...")
print("→ Installing sub-skills...")
for name in skill_names:
print(f" + {name}")
print("→ Installing agents...")
for name in agent_names:
print(f" + {Path(name).stem}")
print("→ Installing scripts...")
for name in script_names:
print(f" + scripts/{name}")
def uninstall(args: argparse.Namespace) -> None:
fs = ProfileFS(Path(args.profile))
manifest = Path(args.manifest)
validate_manifest_path(fs, manifest)
if fs.root_status(manifest.name) is None:
return
managed, raw_manifest = load_v2(fs, manifest)
owned, modified = resolve_ownership(
fs, managed, raw_manifest, args.legacy_inventory, "uninstall", getattr(args, "force_adopt", False),
)
back_up_modified(fs, modified)
transaction = Transaction(fs)
staged_manifest: Path | None = None
try:
for relative in sorted(owned, key=str):
transaction.stage(relative)
print(f" Removed verified package file: {fs.absolute(relative)}")
staged_manifest = stage_manifest(transaction, fs, manifest)
transaction.finish()
except BaseException:
if staged_manifest is not None:
restore_manifest(fs, manifest, staged_manifest)
transaction.close()
raise
for relative in sorted(owned, key=lambda value: len(value.parts), reverse=True):
fs.prune(relative)
print(f" Removed: {manifest}")
def parser() -> argparse.ArgumentParser:
result = argparse.ArgumentParser()
subparsers = result.add_subparsers(dest="command", required=True)
install_parser = subparsers.add_parser("install")
install_parser.add_argument("--source", required=True)
install_parser.add_argument("--profile", required=True)
install_parser.add_argument("--manifest", required=True)
install_parser.add_argument("--stats", required=True)
install_parser.add_argument("--version", required=True)
install_parser.add_argument("--legacy-inventory", required=True)
install_parser.add_argument("--force-adopt", action="store_true")
install_parser.set_defaults(action=install)
uninstall_parser = subparsers.add_parser("uninstall")
uninstall_parser.add_argument("--profile", required=True)
uninstall_parser.add_argument("--manifest", required=True)
uninstall_parser.add_argument("--legacy-inventory")
uninstall_parser.add_argument("--force-adopt", action="store_true")
uninstall_parser.set_defaults(action=uninstall)
return result
def main() -> int:
args = parser().parse_args()
args.action(args)
return 0
if __name__ == "__main__":
sys.exit(main())