portable-agent-layer 0.55.1 → 0.56.0

package/assets/skills/create-pdf/SKILL.md

@@ -76,9 +76,19 @@ Report the file path and size to the user.
 
 ## Styling
 
-Default styling (A4, 25mm margins, GitHub-ish look, table-friendly, page-break-aware headings) is baked into the tool. To customize, edit `tools/md-to-html-pdf.ts` — the `css` string and the `page.pdf({...})` options live side-by-side so fonts, colors, margins, or header/footer templates can be tuned in one place.
+Default styling (A4, 25mm margins, GitHub-ish look, table-friendly, page-break-aware headings) is baked into the tool. Margins and header/footer are configurable per-render via flags — no source edits needed:
 
-For header/footer templates (page numbers, client name, CONFIDENTIAL markings, etc.), extend `page.pdf` with `displayHeaderFooter`, `headerTemplate`, and `footerTemplate` — do NOT combine with CSS `@page` margin-box rules, which duplicate.
+- `--margin <css>` — page margin on all four sides (default `25mm`). E.g. `--margin 12mm` for a denser one-pager.
+- `--header <html|file>` / `--footer <html|file>` — running header/footer on every page. The value is either an inline HTML string or a path to an HTML file. Templates may use Playwright's injected classes: `pageNumber`, `totalPages`, `date`, `title`, `url`.
+
+```bash
+node --experimental-strip-types ~/.pal/skills/create-pdf/tools/md-to-html-pdf.ts report.md --pdf report.pdf \
+  --margin 18mm \
+  --header '<div style="font-size:9px;width:100%;text-align:center;color:#888">CONFIDENTIAL</div>' \
+  --footer '<div style="font-size:9px;width:100%;text-align:right;padding-right:12mm;color:#888"><span class="pageNumber"></span>/<span class="totalPages"></span></div>'
+```
+
+Header/footer templates **need an explicit `font-size`** (Playwright defaults them to 0) and render *inside* the page margin — widen `--margin` so they have room. Do NOT also add CSS `@page` margin-box rules; they duplicate. For deeper changes (fonts, base CSS), edit the `css` string in `tools/md-to-html-pdf.ts`.
 
 ## Translation Variant
 

package/assets/skills/create-pdf/tools/md-to-html-pdf.ts

@@ -7,7 +7,9 @@
 // pipe handling doesn't complete the CDP handshake.
 //
 // Usage:
-//   node --experimental-strip-types ~/.pal/skills/create-pdf/tools/md-to-html-pdf.ts <input.md> [--html <out.html>] [--pdf <out.pdf>]
+//   node --experimental-strip-types ~/.pal/skills/create-pdf/tools/md-to-html-pdf.ts <input.md> \
+//     [--html <out.html>] [--pdf <out.pdf>] [--margin <css>] [--header <html|file>] [--footer <html|file>]
+//   --margin defaults to 25mm (all sides). --header/--footer accept inline HTML or a file path.
 
 import { readFile, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, resolve } from "node:path";
@@ -17,21 +19,44 @@ import { chromium } from "playwright";
 
 const args = process.argv.slice(2);
 if (args.length === 0) {
-  console.error("usage: md-to-html-pdf.ts <input.md> [--html <out>] [--pdf <out>]");
+  console.error(
+    "usage: md-to-html-pdf.ts <input.md> [--html <out>] [--pdf <out>] [--margin <css>] [--header <html|file>] [--footer <html|file>]"
+  );
   process.exit(1);
 }
 
 const input = resolve(args[0]);
 let htmlOut = "";
 let pdfOut = "";
+let margin = "25mm";
+let headerArg = "";
+let footerArg = "";
 for (let i = 1; i < args.length; i++) {
   if (args[i] === "--html") htmlOut = resolve(args[++i]);
   else if (args[i] === "--pdf") pdfOut = resolve(args[++i]);
+  else if (args[i] === "--margin") margin = args[++i];
+  else if (args[i] === "--header") headerArg = args[++i];
+  else if (args[i] === "--footer") footerArg = args[++i];
 }
 const stem = basename(input, extname(input));
 const dir = dirname(input);
-htmlOut ??= resolve(dir, `${stem}.html`);
-pdfOut ??= resolve(dir, `${stem}.pdf`);
+htmlOut ||= resolve(dir, `${stem}.html`);
+pdfOut ||= resolve(dir, `${stem}.pdf`);
+
+// --header/--footer take inline HTML or a path to an HTML file. Playwright renders
+// them inside the page margin, so widen --margin when you use them. Templates may use
+// Playwright's injected classes: pageNumber, totalPages, date, title, url.
+async function resolveTemplate(value: string): Promise<string> {
+  if (!value) return "";
+  try {
+    return await readFile(resolve(value), "utf8");
+  } catch {
+    return value;
+  }
+}
+const headerTemplate = await resolveTemplate(headerArg);
+const footerTemplate = await resolveTemplate(footerArg);
+const displayHeaderFooter = Boolean(headerTemplate || footerTemplate);
 
 const md = await readFile(input, "utf8");
 marked.setOptions({ gfm: true, breaks: false });
@@ -83,9 +108,12 @@ try {
   await page.pdf({
     path: pdfOut,
     format: "A4",
-    margin: { top: "25mm", right: "25mm", bottom: "25mm", left: "25mm" },
+    margin: { top: margin, right: margin, bottom: margin, left: margin },
     printBackground: true,
     preferCSSPageSize: false,
+    displayHeaderFooter,
+    headerTemplate: headerTemplate || "<span></span>",
+    footerTemplate: footerTemplate || "<span></span>",
   });
 } finally {
   await browser.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.55.1",
+  "version": "0.56.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/hooks/lib/security.ts

@@ -3,6 +3,8 @@
  * Used by SecurityValidator.ts (Claude Code) and the opencode plugin.
  */
 
+import { lstatSync } from "node:fs";
+
 /** Dangerous command patterns — always blocked */
 const BLOCKED_COMMANDS: [RegExp, string][] = [
   [/rm\s+-rf\s+[/~]/, "Recursive delete of root or home"],
@@ -67,7 +69,8 @@ const PROTECTED_PATHS: RegExp[] = [
   /\.gnupg\//,
   // Claude Code auto-memory — PAL owns memory; writes here indicate wrong system is being used
   /\.claude\/projects\/[^/]+\/memory\//,
-  PAL_INSTALLED_DIRS_RE,
+  // PAL_INSTALLED_DIRS_RE is enforced by the dedicated branch in checkFilePath
+  // (which exempts personal skill dirs); keeping it here would re-block them.
   // Derived from HOOK_MANAGED_FILES — scoped to managed roots only
   ...HOOK_MANAGED_FILES.map(
     (name) =>
@@ -120,6 +123,22 @@ export function checkBashCommand(cmd: string): string | null {
   return null;
 }
 
+/**
+ * Shipped skills are symlinks into the PAL repo (engine-managed); personal
+ * skills are real dirs authored in place. A not-yet-created skill dir is also
+ * personal (scaffolding). So: symlink → shipped/protected, otherwise → personal.
+ */
+function isShippedSkillPath(normalized: string): boolean {
+  const m = /\.pal\/skills\/([^/]+)/.exec(normalized);
+  if (!m) return false;
+  const skillRoot = normalized.slice(0, m.index + m[0].length);
+  try {
+    return lstatSync(skillRoot).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
 /** Check a file path against protected patterns. Returns a reason string or null. */
 export function checkFilePath(filePath: string): string | null {
   const normalized = filePath.replaceAll("\\", "/");
@@ -141,7 +160,10 @@ export function checkFilePath(filePath: string): string | null {
   if (PAL_INSTALLED_DIRS_RE.test(normalized)) {
     const match = new RegExp(/\.pal[/\\](docs|skills|tools)/).exec(normalized);
     const dir = match ? match[1] : "docs/skills/tools";
-    return `~/.pal/${dir}/ is managed by 'pal install' — edit the source in the PAL repo instead`;
+    const isPersonalSkill = dir === "skills" && !isShippedSkillPath(normalized);
+    if (!isPersonalSkill) {
+      return `~/.pal/${dir}/ is managed by 'pal install' — edit the source in the PAL repo instead`;
+    }
   }
   // Check remaining system-protected paths
   if (PROTECTED_PATHS.some((pattern) => pattern.test(filePath))) {