block-in-file 1.0.0

package/doc/PLAN-envsubst.md

@@ -0,0 +1,200 @@
+# Envsubst Feature Plan
+
+## Overview
+
+Add environment variable interpolation to block content with support for recursive and non-recursive substitution modes.
+
+## Requirements
+
+1. **Envsubst Option**: Add a new `--envsubst` flag that enables environment variable substitution in the input block
+2. **Recursive Mode**: Substitution continues until the result stabilizes (handles nested variables like `${VAR1}` where VAR1 contains `${VAR2}`)
+3. **Non-recursive Mode**: Single pass substitution only (matches standard envsubst behavior)
+4. **Variable Syntax**: Support `${VAR}` and `$VAR` syntax for environment variables
+
+## Implementation Plan
+
+### Phase 1: Core Envsubst Module
+
+Create `src/envsubst.ts` with:
+
+- `substitute(text: string, options: EnvsubstOptions): string` - Main substitution function
+- Support for `${VAR}` syntax (priority)
+- Support for `$VAR` syntax (fallback)
+- Recursive mode: loop until stable or max iterations reached
+- Non-recursive mode: single pass substitution
+
+### Phase 2: Configuration Updates
+
+Update `src/plugins/config.ts`:
+
+- Add `envsubst` option to ConfigExtension interface
+- Add CLI option `--envsubst` with values: `true`, `false`, `recursive`, `non-recursive`
+- Default: `false` (disabled)
+- Map values: `true` → `recursive`, `non-recursive` → single pass
+
+Update `src/types.ts`:
+
+- Add `envsubst` field to `BlockInFileOptions` interface
+- Add `envsubst` field to default options
+
+### Phase 3: Integration
+
+Update `src/file-processor.ts`:
+
+- Import envsubst module
+- Apply envsubst to `inputBlock` before processing
+- Pass envsubst option through ProcessContext
+
+Update `block-in-file.ts`:
+
+- Pass envsubst from config to processFile context
+
+### Phase 4: Testing
+
+Create test files:
+
+- `test/envsubst.test.ts` - Unit tests for substitution logic
+- `test/envsubst-integration.test.ts` - End-to-end CLI tests
+- `test/envsubst-edge-cases.test.ts` - Edge case tests
+
+## Design Decisions
+
+### Variable Syntax Priority
+
+1. `${VAR}` - Preferred, explicit syntax
+2. `$VAR` - Supported for compatibility with shell syntax
+
+### Undefined Variables
+
+- **Decision**: Replace with empty string (not "undefined" or leave as-is)
+- Matches standard envsubst behavior
+- Allows optional variables without errors
+
+### Recursive Mode Safety
+
+- Maximum iterations: 100 (prevent infinite loops)
+- Stop when: `previous === current` or max iterations reached
+- Handles nested variables: `${VAR1}` where VAR1="${VAR2}" expands fully
+
+### Non-recursive Mode
+
+- Single pass only (matches standard envsubst)
+- Substitute variables once with current environment values
+- No re-evaluation of substituted values
+- Nested braces like `${VAR${NESTED}}` will expand inner but not result
+
+### Escaping Behavior
+
+- **Decision**: Backslash escaping NOT supported (matches envsubst quirky behavior)
+- `\${VAR}` becomes `\value` (backslash is literal, substitution still happens)
+- This is consistent with standard envsubst, not traditional escaping
+
+## Edge Cases Handled
+
+1. **Empty variable names**: `${}` - NOT matched by regex pattern (requires at least one character after `$` and before `{`), remains as-is
+2. **Lone dollar sign**: `$` - NOT matched by regex pattern (requires variable name), remains as-is
+3. **Nested braces**: `${VAR${NESTED}}`
+   - Recursive mode: expands fully (NESTED → inner, then VARinner → final)
+   - Non-recursive mode: expands inner only (NESTED → inner, result is `${VARinner}`)
+4. **Invalid variable names**: `${VAR-INVALID}`, `${1VAR}` - NOT matched (regex requires `[a-zA-Z_][a-zA-Z0-9_]*`), remain as-is
+5. **Variables with underscores**: `${MY_LONG_VAR_NAME_123}` - Matched and substituted correctly
+6. **Malformed syntax**: `${` or `$` at end of string - NOT matched by patterns, remain as-is
+
+## API Changes
+
+### CLI Options
+
+```bash
+--envsubst           # Enable recursive substitution
+--envsubst=recursive # Explicit recursive mode
+--envsubst=non-recursive # Single pass substitution (like envsubst)
+--envsubst=false     # Disable (default)
+```
+
+### Programmatic API
+
+```typescript
+const options: BlockInFileOptions = {
+  // ... other options
+  envsubst: true, // recursive (expand until stable)
+  envsubst: "recursive", // explicit recursive mode
+  envsubst: "non-recursive", // single pass (like envsubst)
+  envsubst: false, // disabled
+};
+```
+
+## Example Usage
+
+### Basic Substitution
+
+```bash
+export MY_VAR="hello world"
+echo "content: \${MY_VAR}" | block-in-file -i - -o output.txt --envsubst
+# Results in: content: hello world
+```
+
+### Recursive Substitution (handles nested variables)
+
+```bash
+export VAR1="value1"
+export VAR2="prefix \${VAR1}"
+echo "result: \${VAR2}" | block-in-file -i - -o output.txt --envsubst
+# Results in: result: prefix value1
+```
+
+### Non-recursive (single pass, like envsubst)
+
+```bash
+export VAR1="value1"
+export VAR2="prefix \${VAR1}"
+echo "result: \${VAR2}" | block-in-file -i - -o output.txt --envsubst=non-recursive
+# Results in: result: prefix ${VAR1} (VAR1 not expanded in single pass)
+```
+
+### Undefined Variables
+
+```bash
+export DEFINED_VAR="value"
+echo "\${DEFINED_VAR} and \${UNDEFINED_VAR}" | block-in-file -i - -o output.txt --envsubst
+# Results in: value and  (undefined becomes empty string)
+```
+
+### Empty Variable Names
+
+```bash
+echo "value: \${}" | block-in-file -i - -o output.txt --envsubst
+# Results in: value: ${} (pattern doesn't match, stays as-is)
+```
+
+## Testing Strategy
+
+1. **Unit Tests** (envsubst.ts):
+   - Basic substitution with `${VAR}`
+   - Basic substitution with `$VAR`
+   - Multiple variables in one string
+   - Recursive substitution with nesting
+   - Non-recursive single pass
+   - Undefined variable handling (becomes empty string)
+   - Malformed syntax handling
+   - Edge cases (empty string, no variables, invalid names)
+
+2. **Integration Tests**:
+   - End-to-end with block-in-file command
+   - Combination with other options (mode, validate, etc.)
+   - File input and stdin input
+
+3. **Edge Case Tests**:
+   - Empty variable names `${}`
+   - Lone dollar sign `$`
+   - Nested braces in both modes
+   - Invalid variable names
+   - Variables with underscores and numbers
+   - Backslash escaping behavior
+
+## Implementation Order
+
+1. ✅ Create envsubst module with substitution logic
+2. ✅ Add configuration options
+3. ✅ Integrate into file processor
+4. ✅ Add tests (unit, integration, edge cases)
+5. ✅ Update documentation (PLAN-envsubst.md)

package/doc/PLAN-restructure.md

@@ -0,0 +1,114 @@
+# Restructure Plan
+
+## Current Issues
+
+1. **Single file complexity** - `block-in-file.ts` contains 215 lines mixing multiple responsibilities
+2. **Non-testable code** - No way to unit test individual components
+3. **Global mutable state** - `defaults` and `setDefaults()` create coupling issues
+4. **Poor separation of concerns** - File I/O, parsing, and logic intermingled
+5. **Dead code** - Commented-out blocks that should be removed
+
+## Target Structure
+
+```
+src/
+├── types.ts           # All type definitions, interfaces
+├── input.ts           # Input handling (_input, stream reading)
+├── block-parser.ts    # Block finding, parsing, insertion logic
+├── output.ts          # Output writing, formatting
+├── defaults.ts        # Default configuration (immutable pattern)
+├── block-in-file.ts   # Main class orchestrating components
+├── cli.ts             # CLI interface (renamed from cliffy.ts)
+└── index.ts           # Public API exports
+```
+
+## Component Breakdown
+
+### `types.ts`
+
+- `BlockInFileOptions` interface
+- `CreateArg` type
+- `InputOptions` interface
+- All shared types
+
+### `input.ts`
+
+- `get<T>()` utility function
+- `createOpt()` function
+- `_input()` function
+- Stream handling utilities
+
+### `block-parser.ts`
+
+- Block detection logic (finding opener/closer)
+- Insertion position calculation (before/after matching)
+- Line-by-line processing state machine
+- Returns structured result: `{ outputs: string[], matched: number, opened?: number }`
+
+### `output.ts`
+
+- `formatOutputs()` - Join lines with appropriate line endings
+- `writeOutput()` - Handle different output modes (file, stdout, none)
+- Diff generation (when implemented)
+
+### `defaults.ts`
+
+- Immutable default configuration object
+- `getDefaultOptions()` function
+- No mutable exports
+
+### `block-in-file.ts`
+
+- Main `BlockInFile` class
+- `run()` method that orchestrates components
+- Minimal logic, delegates to specialized modules
+
+### `cli.ts`
+
+- All Cliffy/CLI logic
+- Argument parsing
+- Environment variable handling
+- Renamed from `cliffy.ts` for clarity
+
+### `index.ts`
+
+- Public API exports
+- Re-exports for convenience
+
+## Migration Steps
+
+1. **Create new files** with empty structure
+2. **Extract types** to `types.ts`
+3. **Move input functions** to `input.ts`
+4. **Extract parsing logic** to `block-parser.ts` (core complexity)
+5. **Extract output logic** to `output.ts`
+6. **Create defaults module** with immutable pattern
+7. **Refactor main class** to use new components
+8. **Update CLI imports**
+9. **Verify functionality** with existing examples
+10. **Add tests** for individual components
+
+## Testing Strategy
+
+After restructuring:
+
+- Unit test `block-parser.ts` with mock inputs
+- Unit test `output.ts` with various output modes
+- Unit test `input.ts` file opening scenarios
+- Integration test full `BlockInFile.run()` flow
+- CLI tests for argument parsing
+
+## Benefits
+
+- **Maintainability** - Clear file boundaries make changes easier
+- **Testability** - Components can be unit tested independently
+- **Reusability** - Individual modules can be used separately
+- **Readability** - Smaller files are easier to understand
+- **Onboarding** - New contributors can navigate code faster
+
+## Backward Compatibility
+
+- Public API remains unchanged
+- CLI interface unchanged
+- Existing functionality preserved
+- Only internal structure changes

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "block-in-file",
+  "version": "1.0.0",
+  "description": "Insert & update blocks of text in files",
+  "keywords": [
+    "block",
+    "file",
+    "insert",
+    "text"
+  ],
+  "license": "ISC",
+  "author": "",
+  "bin": {
+    "block-in-file": "./block-in-file.ts"
+  },
+  "type": "module",
+  "dependencies": {
+    "@gunshi/plugin": "^0.27.5",
+    "args-tokenizer": "^0.3.0",
+    "gunshi": "^0.28.0",
+    "tinyexec": "^1.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260201.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "concurrently": "^9.2.1",
+    "oxfmt": "^0.27.0",
+    "oxlint": "^1.42.0",
+    "tsx": "^4.21.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "check:ts": "tsgo --noEmit",
+    "check:lint": "oxlint",
+    "check:fmt": "oxfmt --check",
+    "fix:lint": "oxlint --fix",
+    "fix:fmt": "oxfmt",
+    "check": "concurrently \"pnpm:check:*\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/attributes.ts

@@ -0,0 +1,161 @@
+import { x } from "tinyexec";
+import type { LoggerExtension } from "./plugins/logger.ts";
+import type { IOExtension } from "./plugins/io.ts";
+
+export interface AttributeChange {
+  mode: "+" | "-" | "=";
+  attribute: string;
+}
+
+export interface AttributeOptions {
+  attributes?: string;
+  debug: boolean;
+  logger: LoggerExtension;
+  io: IOExtension;
+}
+
+export function parseAttributes(attrString: string): AttributeChange[] {
+  const changes: AttributeChange[] = [];
+
+  if (!attrString || attrString.trim().length === 0) {
+    return changes;
+  }
+
+  const tokens = attrString.trim().split(/\s+/);
+
+  for (const token of tokens) {
+    if (token.length === 0) continue;
+
+    const mode = token[0] as "+" | "-" | "=";
+    const attr = token.slice(1);
+
+    if (!/^[+\-=]/.test(mode) || !/^[a-zA-Z]+$/.test(attr)) {
+      throw new Error(`Invalid attribute syntax: ${token}`);
+    }
+
+    changes.push({ mode, attribute: attr });
+  }
+
+  return changes;
+}
+
+export async function supportsChattr(): Promise<boolean> {
+  if (process.platform !== "linux") {
+    return false;
+  }
+
+  try {
+    await x("which", ["chattr"], { throwOnError: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function runChattr(args: string[]): Promise<void> {
+  try {
+    await x("chattr", args, { throwOnError: true });
+  } catch (err) {
+    const error = err as Error & { stderr?: string; exitCode?: number };
+    const stderr = error.stderr?.trim() || "";
+    const code = error.exitCode;
+    throw new Error(
+      `chattr failed${code !== undefined ? ` with code ${code}` : ""}${stderr ? `: ${stderr}` : ""}`,
+    );
+  }
+}
+
+async function runLsattr(filePath: string): Promise<string> {
+  try {
+    const result = await x("lsattr", [filePath], { throwOnError: true });
+    return result.stdout.trim();
+  } catch (err) {
+    const error = err as Error & { stderr?: string; exitCode?: number };
+    const stderr = error.stderr?.trim() || "";
+    const code = error.exitCode;
+    throw new Error(
+      `lsattr failed${code !== undefined ? ` with code ${code}` : ""}${stderr ? `: ${stderr}` : ""}`,
+    );
+  }
+}
+
+export async function applyAttributes(
+  filePath: string,
+  changes: AttributeChange[],
+  debug: boolean,
+  logger: LoggerExtension,
+): Promise<void> {
+  if (changes.length === 0) {
+    return;
+  }
+
+  if (!(await supportsChattr())) {
+    throw new Error(
+      "chattr is not available on this system. File attributes require Linux and the chattr command.",
+    );
+  }
+
+  if (debug) {
+    logger.debug(
+      `Applying attributes to ${filePath}: ${changes.map((c) => `${c.mode}${c.attribute}`).join(" ")}`,
+    );
+  }
+
+  for (const change of changes) {
+    await runChattr([`${change.mode}${change.attribute}`, filePath]);
+  }
+
+  if (debug) {
+    try {
+      const attrs = await runLsattr(filePath);
+      logger.debug(`File attributes after chattr: ${attrs}`);
+    } catch (err) {
+      logger.debug(`Could not verify attributes with lsattr: ${(err as Error).message}`);
+    }
+  }
+}
+
+export async function applyAttributesSafe(
+  filePath: string,
+  changes: AttributeChange[],
+  opts: AttributeOptions,
+): Promise<void> {
+  const { debug, logger } = opts;
+
+  if (changes.length === 0) {
+    return;
+  }
+
+  if (!(await supportsChattr())) {
+    if (debug) {
+      logger.debug("chattr not available on this system, skipping attribute setting");
+    }
+    return;
+  }
+
+  if (process.platform !== "linux") {
+    if (debug) {
+      logger.debug(`File attributes are only supported on Linux, skipping for ${process.platform}`);
+    }
+    return;
+  }
+
+  if (debug) {
+    logger.debug(
+      `Attempting to set attributes on ${filePath}: ${changes.map((c) => `${c.mode}${c.attribute}`).join(" ")}`,
+    );
+  }
+
+  try {
+    await applyAttributes(filePath, changes, debug, logger);
+  } catch (err) {
+    const errorMsg = (err as Error).message;
+    if (errorMsg.includes("Operation not permitted") || errorMsg.includes("Permission denied")) {
+      logger.warn(
+        `Insufficient privileges to set file attributes. Root or CAP_LINUX_IMMUTABLE capability required.`,
+      );
+    } else {
+      logger.warn(`Failed to set file attributes: ${errorMsg}`);
+    }
+  }
+}

package/src/backup.ts

@@ -0,0 +1,180 @@
+import * as crypto from "node:crypto";
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+
+export type BackupMode = "iterate" | "fail" | "overwrite";
+
+export interface BackupOptions {
+  enabled: boolean;
+  suffix: string;
+  backupDir?: string;
+  stateOnFail?: BackupMode;
+}
+
+export interface TemplateVariables {
+  date: string;
+  time: string;
+  iso: string;
+  epoch: string;
+  md5?: string;
+  sha256?: string;
+}
+
+export function generateTemplateVariables(content?: string): TemplateVariables {
+  const now = new Date();
+
+  const variables: TemplateVariables = {
+    date: now.toISOString().split("T")[0],
+    time: now.toTimeString().split(" ")[0].replace(/:/g, ""),
+    iso: now.toISOString(),
+    epoch: Math.floor(now.getTime() / 1000).toString(),
+  };
+
+  if (content) {
+    const md5 = crypto.createHash("md5").update(content).digest("hex");
+    const sha256 = crypto.createHash("sha256").update(content).digest("hex");
+    variables.md5 = md5.substring(0, 8);
+    variables.sha256 = sha256.substring(0, 8);
+  }
+
+  return variables;
+}
+
+export function replaceTemplateVariables(template: string, variables: TemplateVariables): string {
+  let result = template;
+
+  for (const [key, value] of Object.entries(variables)) {
+    result = result.replaceAll(`{${key}}`, value);
+  }
+
+  return result;
+}
+
+export function generateBackupPaths(
+  originalPath: string,
+  suffix: string,
+  variables: TemplateVariables,
+  backupDir?: string,
+): string {
+  const basePath = backupDir ? path.join(backupDir, path.basename(originalPath)) : originalPath;
+  const processedSuffix = replaceTemplateVariables(suffix, variables);
+  return `${basePath}${processedSuffix}`;
+}
+
+export async function detectGitRepo(dir: string): Promise<boolean> {
+  try {
+    const gitPath = path.join(dir, ".git");
+    await fs.access(gitPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isPathInGitRepo(filePath: string): Promise<boolean> {
+  const dir = path.dirname(filePath);
+  return detectGitRepo(dir);
+}
+
+export async function createBackup(originalPath: string, backupPath: string): Promise<void> {
+  await fs.copyFile(originalPath, backupPath);
+
+  const isGitRepo = await isPathInGitRepo(backupPath);
+  if (isGitRepo) {
+    const gitignorePath = path.join(path.dirname(backupPath), ".gitignore");
+
+    try {
+      const gitignore = await fs.readFile(gitignorePath, "utf-8");
+      const backupName = path.basename(backupPath);
+
+      if (!gitignore.includes(backupName)) {
+        await fs.appendFile(gitignorePath, `\n${backupName}\n`);
+      }
+    } catch {
+      await fs.writeFile(gitignorePath, `${path.basename(backupPath)}\n`);
+    }
+  }
+}
+
+export async function findAvailableBackupPath(
+  baseBackupPath: string,
+  mode: BackupMode = "iterate",
+): Promise<string | null> {
+  try {
+    await fs.access(baseBackupPath);
+
+    if (mode === "iterate") {
+      let counter = 1;
+      while (true) {
+        const backupPath = `${baseBackupPath}.${counter}`;
+        try {
+          await fs.access(backupPath);
+          counter++;
+        } catch {
+          return backupPath;
+        }
+      }
+    } else if (mode === "overwrite") {
+      return baseBackupPath;
+    } else {
+      return null;
+    }
+  } catch {
+    return baseBackupPath;
+  }
+}
+
+export async function performBackup(
+  originalPath: string,
+  options: BackupOptions,
+  content?: string,
+): Promise<string | null> {
+  if (!options.enabled) {
+    return null;
+  }
+
+  const variables = generateTemplateVariables(content);
+  const backupPath = generateBackupPaths(
+    originalPath,
+    options.suffix,
+    variables,
+    options.backupDir,
+  );
+
+  try {
+    await fs.access(originalPath);
+
+    const finalBackupPath = await findAvailableBackupPath(backupPath, options.stateOnFail);
+
+    if (finalBackupPath === null && options.stateOnFail === "fail") {
+      throw new Error(
+        `Backup failed: backup file already exists and state-on-fail is set to 'fail'`,
+      );
+    }
+
+    if (finalBackupPath) {
+      await createBackup(originalPath, finalBackupPath);
+      return finalBackupPath;
+    }
+  } catch (err) {
+    if (options.stateOnFail === "fail") {
+      throw err;
+    }
+  }
+
+  return null;
+}
+
+export function parseBackupOption(backupArgs: string[] | undefined): BackupOptions {
+  if (!backupArgs || backupArgs.length === 0) {
+    return { enabled: false, suffix: "" };
+  }
+
+  const joined = backupArgs.join(".");
+  const suffix = joined.startsWith(".") ? joined : `.${joined}`;
+
+  return {
+    enabled: true,
+    suffix,
+  };
+}