@dalzoubi/dev-agents-sync 1.0.15 → 1.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalzoubi/dev-agents-sync",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "type": "module",
   "description": "CLI that syncs managed dev-agent prompts into consumer repos (.claude/ and/or .cursor/).",
   "license": "UNLICENSED",

package/src/commands/check.mjs

@@ -15,7 +15,8 @@ function filterFileMapByTargets(fileMap, targets) {
   const out = {};
   for (const [key, content] of Object.entries(fileMap)) {
     const prefix = key.split('/')[0];
-    if (targets.includes(prefix)) {
+    // root-targeted files are always checked regardless of the lockfile's targets.
+    if (prefix === 'root' || targets.includes(prefix)) {
       out[key] = content;
     }
   }

package/src/commands/init.mjs

@@ -6,13 +6,13 @@
  * Supports --dry-run (no writes).
  */
 
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { writeLockfile, DEFAULT_SOURCE } from '../lockfile.mjs';
 import { resolveRange } from '../range.mjs';
 import { resolveConsumerPath, writeManagedFile, normalizeFileMap } from '../writer.mjs';
-import { hasMarker } from '../marker.mjs';
+import { hasMarker, hasMarkerOnFirstLine } from '../marker.mjs';
 
 const DEFAULT_RANGE = '^1';
 const ALL_TARGETS = ['claude', 'cursor'];
@@ -45,7 +45,8 @@ function filterFileMapByTargets(fileMap, targets) {
   const out = {};
   for (const [key, content] of Object.entries(fileMap)) {
     const prefix = key.split('/')[0];
-    if (targets.includes(prefix)) {
+    // root-targeted files are always emitted regardless of the lockfile's targets.
+    if (prefix === 'root' || targets.includes(prefix)) {
       out[key] = content;
     }
   }
@@ -109,7 +110,8 @@ export async function runInit(consumerCwd, opts = {}) {
   const plannedWrites = [];
   for (const [relKey, content] of Object.entries(scoped)) {
     const absPath = resolveConsumerPath(consumerCwd, relKey);
-    plannedWrites.push({ relKey, absPath, content });
+    const isNew = relKey.startsWith('root/') && !existsSync(absPath);
+    plannedWrites.push({ relKey, absPath, content, isNew });
   }
 
   if (dryRun) {
@@ -122,12 +124,15 @@ export async function runInit(consumerCwd, opts = {}) {
     };
   }
 
-  // Pre-flight collision check (so we fail before any writes)
+  // Pre-flight collision check (so we fail before any writes).
+  // Root-targeted files require the marker on the literal first line;
+  // other managed files use the lenient (post-frontmatter) check.
   for (const { absPath, relKey } of plannedWrites) {
     if (existsSync(absPath) && !force) {
-      const fs = await import('node:fs');
-      const existing = fs.readFileSync(absPath, 'utf8');
-      if (!hasMarker(existing)) {
+      const existing = readFileSync(absPath, 'utf8');
+      const isRootTarget = relKey.startsWith('root/');
+      const managed = isRootTarget ? hasMarkerOnFirstLine(existing) : hasMarker(existing);
+      if (!managed) {
         const err = new Error(
           `refusing to overwrite unmanaged file at ${relKey} ` +
             `(${absPath}). Delete/rename it or pass --force to overwrite.`,
@@ -138,8 +143,14 @@ export async function runInit(consumerCwd, opts = {}) {
     }
   }
 
-  for (const { absPath, relKey, content } of plannedWrites) {
+  for (const { absPath, relKey, content, isNew } of plannedWrites) {
     writeManagedFile({ absPath, relKey, content, force: true });
+    if (isNew) {
+      const consumerRelPath = relKey.slice('root/'.length);
+      process.stderr.write(
+        `info: dev-agents-sync: created ${consumerRelPath} (new in v${resolvedVersion}; see release notes)\n`,
+      );
+    }
   }
 
   writeLockfile(consumerCwd, {

package/src/commands/update.mjs

@@ -10,13 +10,14 @@ import { existsSync, readFileSync } from 'node:fs';
 import { readLockfile, writeLockfile } from '../lockfile.mjs';
 import { resolveRange } from '../range.mjs';
 import { resolveConsumerPath, writeManagedFile, normalizeFileMap } from '../writer.mjs';
-import { hasMarker } from '../marker.mjs';
+import { hasMarker, hasMarkerOnFirstLine } from '../marker.mjs';
 
 function filterFileMapByTargets(fileMap, targets) {
   const out = {};
   for (const [key, content] of Object.entries(fileMap)) {
     const prefix = key.split('/')[0];
-    if (targets.includes(prefix)) {
+    // root-targeted files are always emitted regardless of the lockfile's targets.
+    if (prefix === 'root' || targets.includes(prefix)) {
       out[key] = content;
     }
   }
@@ -56,7 +57,8 @@ export async function runUpdate(consumerCwd, opts = {}) {
   const plannedWrites = [];
   for (const [relKey, content] of Object.entries(scoped)) {
     const absPath = resolveConsumerPath(consumerCwd, relKey);
-    plannedWrites.push({ relKey, absPath, content });
+    const isNew = relKey.startsWith('root/') && !existsSync(absPath);
+    plannedWrites.push({ relKey, absPath, content, isNew });
   }
 
   if (dryRun) {
@@ -68,11 +70,14 @@ export async function runUpdate(consumerCwd, opts = {}) {
     };
   }
 
-  // Collision check
+  // Collision check. Root-targeted files require the marker on the literal
+  // first line; other managed files use the lenient (post-frontmatter) check.
   for (const { absPath, relKey } of plannedWrites) {
     if (existsSync(absPath) && !force) {
       const existing = readFileSync(absPath, 'utf8');
-      if (!hasMarker(existing)) {
+      const isRootTarget = relKey.startsWith('root/');
+      const managed = isRootTarget ? hasMarkerOnFirstLine(existing) : hasMarker(existing);
+      if (!managed) {
         const err = new Error(
           `refusing to overwrite unmanaged file at ${relKey} ` +
             `(${absPath}). The marker is missing — pass --force to overwrite.`,
@@ -83,8 +88,14 @@ export async function runUpdate(consumerCwd, opts = {}) {
     }
   }
 
-  for (const { absPath, relKey, content } of plannedWrites) {
+  for (const { absPath, relKey, content, isNew } of plannedWrites) {
     writeManagedFile({ absPath, relKey, content, force: true });
+    if (isNew) {
+      const consumerRelPath = relKey.slice('root/'.length);
+      process.stderr.write(
+        `info: dev-agents-sync: created ${consumerRelPath} (new in v${targetVersion}; see release notes)\n`,
+      );
+    }
   }
 
   writeLockfile(consumerCwd, {

package/src/marker.mjs

@@ -51,6 +51,16 @@ export function hasMarker(content) {
   return MARKER_RE.test(first);
 }
 
+/**
+ * Stricter check used for root-targeted files: the marker must be the literal
+ * first physical line of the file, with no frontmatter strip or blank-line skip.
+ */
+export function hasMarkerOnFirstLine(content) {
+  if (!content) return false;
+  const firstLine = content.split(/\r?\n/)[0] ?? '';
+  return MARKER_RE.test(firstLine);
+}
+
 export function extractMarkerVersion(content) {
   if (!content) return null;
   const body = stripFrontmatter(content);

package/src/writer.mjs

@@ -10,12 +10,15 @@
 
 import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { hasMarker } from './marker.mjs';
+import { hasMarker, hasMarkerOnFirstLine } from './marker.mjs';
 
 const TARGET_PREFIX = {
   claude: '.claude',
   cursor: '.cursor',
   copilot: '.github',
+  // root resolves to the consumer repo root (empty prefix, no subdirectory).
+  // Root-targeted files are emitted unconditionally regardless of the lockfile's targets.
+  root: '',
 };
 
 // Subdirectories that uniquely identify a target. Used to normalize
@@ -40,7 +43,7 @@ export function normalizeFileMap(fileMap) {
   for (const [key, content] of Object.entries(fileMap)) {
     const norm = key.replace(/\\/g, '/');
     const first = norm.split('/')[0];
-    if (first === 'claude' || first === 'cursor' || first === 'copilot') {
+    if (first === 'claude' || first === 'cursor' || first === 'copilot' || first === 'root') {
       out[norm] = content;
       continue;
     }
@@ -90,17 +93,18 @@ export function resolveConsumerPath(consumerRoot, relPath) {
   }
 
   const [target, ...rest] = parts;
-  const prefix = TARGET_PREFIX[target];
-  if (!prefix) {
+  if (!(target in TARGET_PREFIX)) {
     throw new PathError(
       `invalid path: unknown target prefix in ${JSON.stringify(relPath)} ` +
         `(allowed: ${Object.keys(TARGET_PREFIX).join(', ')})`,
     );
   }
+  const prefix = TARGET_PREFIX[target];
   if (rest.length === 0) {
     throw new PathError(`invalid path (target only): ${JSON.stringify(relPath)}`);
   }
 
+  // root target: prefix is '' so path.join collapses to consumerRoot/<rest>
   return path.join(consumerRoot, prefix, ...rest);
 }
 
@@ -111,7 +115,12 @@ export function resolveConsumerPath(consumerRoot, relPath) {
 export function writeManagedFile({ absPath, relKey, content, force }) {
   if (existsSync(absPath) && !force) {
     const existing = readFileSync(absPath, 'utf8');
-    if (!hasMarker(existing)) {
+    // Root-targeted files require the marker on the literal first physical line.
+    // Any other placement (buried, after frontmatter, after blank line) is treated
+    // as user modification — the file is considered unmanaged.
+    const isRootTarget = typeof relKey === 'string' && relKey.startsWith('root/');
+    const managed = isRootTarget ? hasMarkerOnFirstLine(existing) : hasMarker(existing);
+    if (!managed) {
       const err = new Error(
         `refusing to overwrite unmanaged file at ${relKey}: ` +
           `${absPath} has no managed-by marker. ` +