touch-all 1.2.1 → 2.1.0

package/README.md

@@ -10,11 +10,13 @@ It behaves like `mkdir -p` and `touch` combined, creating directories and files
 
 - Accepts tree strings in **box-drawing** (`├──`, `└──`, `│`) or **indentation** (spaces) format
 - Trailing slash `/` marks a directory; no trailing `/` marks a file
-- Inline comments stripped automatically (`# ...` and `// ...`)
-- `--dry-run` parses and validates without touching the file system
-- `--verbose` prints every created path
-- Path traversal protection — no item can escape the target directory
+- Symlink creation with `link-name -> target` syntax
+- Inline comments stripped automatically (`# ...`, `// ...`, `<- ...`, `← ...`)
+- `--dry-run` (`-n`) parses and validates without touching the file system
+- Prints a summary line on success (`✓ Done. N items created.`); `--verbose` adds per-item detail
+- Path traversal protection — no file, folder, or symlink target can escape the target directory
 - Importable as a Node.js library with full TypeScript types
+- Pipable interface to run as `echo tree | touch-all` in CI or scripts
 
 ## Installation
 
@@ -59,13 +61,20 @@ touch-all "..." --dry-run
 touch-all "..." -n
 ```
 
-- `--verbose` , `-v` – prints every created path to the console. Useful for seeing exactly what will be created, especially with complex structures. It's an alias for `--log-level info`
+- `--verbose` , `-v` – prints every created path to the console. Useful for seeing exactly what will be created, especially with complex structures. By default only a summary line is printed on success (`✓ Done. N items created.`). `--verbose` adds per-item detail.
 
 ```bash
 touch-all "..." --verbose
 touch-all "..." -v
 ```
 
+- `--yes` , `-y` – skips the confirmation prompt when symlinks point outside the project root. Required in non-interactive environments (scripts, CI).
+
+```bash
+touch-all "..." --yes
+touch-all "..." -y
+```
+
 - `--completions` – generates a completion script for a specific shell. Supported shells: `sh`, `bash`, `fish`, `zsh`.
 - `--log-level` – sets the minimum log level for a command. Supported levels: `all`, `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `none`. The default log level is `warning`.
 - `--help` , `-h` – shows the help documentation for a command.
@@ -112,11 +121,34 @@ Both formats produce identical results.
 | `name`            | file                             |
 | `dir/sub/`        | directory at an explicit subpath |
 | `dir/sub/file.ts` | file at an explicit subpath      |
-| `... # comment`   | ignored (stripped)               |
+| `... #  comment`  | ignored (stripped)               |
 | `... // comment`  | ignored (stripped)               |
+| `... <- comment`  | ignored (stripped)               |
+| `... ←  comment`  | ignored (stripped)               |
+| `name -> target`  | symlink pointing to `target`     |
 
 Items at the root level (no indentation / no parent) are created directly inside the target directory.
 
+### Symlinks
+
+Use `link-name -> target` to create a symlink. The target is passed as-is to the OS — use paths relative to the symlink's location, just as you would in a shell.
+
+```
+my-project/
+├─ src/
+│  ├─ index.ts
+│  └─ utils -> ../shared/utils.ts   # symlink to a sibling directory
+└─ shared/
+   └─ utils.ts
+```
+
+If `target` ends with `/`, the symlink is created as a directory symlink (relevant on Windows). The link name's suffix is ignored.
+
+> [!WARNING]
+> If any symlink target resolves outside the project root (`--path`), `touch-all` will prompt for confirmation before proceeding. Use `--yes` to skip the prompt in scripts or CI.
+>
+> When using `fileStructureCreator` directly as a library, outside-root symlinks are rejected by default with a `PathTraversalError`. Pass `{ allowOutsideSymlinks: true }` as the third argument to allow them.
+
 ## Library API
 
 ```bash
@@ -128,36 +160,44 @@ import {
   parserFolderStructure,
   fileStructureCreator,
   resolveProjectPathToBase,
+  isSymlinkOutsideRoot,
   PathTraversalError,
-  FsError,
 } from 'touch-all'
 import type { ParserResult, ParserResultLineItem } from 'touch-all'
 ```
 
 ### `parserFolderStructure(tree: string): ParserResult`
 
-Parses a tree string into a flat list of `type ParserResult = { path: string, isFile: boolean }` items. Pure function, no I/O.
+Parses a tree string into a flat list of items. Pure function, no I/O.
+
+Each item is one of:
+
+```ts
+type ParserResultLineItem =
+  | { type: 'file'; path: string }
+  | { type: 'folder'; path: string }
+  | { type: 'symlink'; path: string; target: string }
+```
 
 ```ts
 const items = parserFolderStructure(`
   src/
     index.ts
+    link -> ../shared.ts
 `)
 // [
-//    {
-//      path: 'src',
-//      isFile: false
-//     }, {
-//      path: 'src/index.ts',
-//      isFile: true
-//     }
+//   { type: 'folder',  path: 'src' },
+//   { type: 'file',    path: 'src/index.ts' },
+//   { type: 'symlink', path: 'src/link', target: '../shared.ts' },
 // ]
 ```
 
-### `fileStructureCreator(items: ParserResult, basePath: string): Effect<void, FsError | PathTraversalError>`
+### `fileStructureCreator(items, basePath, options?): Effect<void, PathTraversalError>`
 
 Creates the parsed structure on disk under `basePath`. Returns an [Effect](https://effect.website/).
 
+By default, symlinks whose targets resolve outside `basePath` are rejected with `PathTraversalError`. Pass `{ allowOutsideSymlinks: true }` to allow them.
+
 ```ts
 import { Effect } from 'effect'
 import { NodeContext, NodeRuntime } from '@effect/platform-node'
@@ -165,22 +205,45 @@ import { NodeContext, NodeRuntime } from '@effect/platform-node'
 const projectDirectory = '/absolute/target/path'
 const items = parserFolderStructure(tree)
 
+// Default: outside-root symlinks are rejected
 fileStructureCreator(items, projectDirectory).pipe(Effect.provide(NodeContext.layer), NodeRuntime.runMain)
+
+// Opt out of symlink containment check
+fileStructureCreator(items, projectDirectory, { allowOutsideSymlinks: true }).pipe(
+  Effect.provide(NodeContext.layer),
+  NodeRuntime.runMain
+)
+```
+
+### `isSymlinkOutsideRoot(linkPath, target, basePath, path): boolean`
+
+Pure function that returns `true` if a symlink target resolves outside `basePath`. Useful for pre-validating items before passing them to `fileStructureCreator`.
+
+```ts
+import { Path } from '@effect/platform'
+import { Effect } from 'effect'
+import { NodeContext } from '@effect/platform-node'
+import { isSymlinkOutsideRoot } from 'touch-all'
+
+Effect.gen(function* () {
+  const path = yield* Path.Path
+  const outside = isSymlinkOutsideRoot('src/link', '../../etc/passwd', '/project', path)
+  // true — target escapes /project
+}).pipe(Effect.provide(NodeContext.layer))
 ```
 
 ### `resolveProjectPathToBase(projectPath: string, basePath: string): Effect<string, PathTraversalError>`
 
 Resolves `projectPath` relative to `basePath` and rejects any path that would escape `basePath` (path traversal protection).
 
-> [!CAUTION]
+> [!WARNING]
 > `projectPath` cannot traverse outside of `basePath`. If `projectPath` is absolute, it treated as relative to `basePath`. If `projectPath` is relative, it is resolved against `basePath`. In either case, if the resulting path is outside of `basePath`, a `PathTraversalError` is thrown.
 
 ### Error types
 
-| Class                | `_tag`                 | When thrown                                                     |
-| -------------------- | ---------------------- | --------------------------------------------------------------- |
-| `PathTraversalError` | `'PathTraversalError'` | Resolved path escapes `basePath`, or `basePath` is not absolute |
-| `FsError`            | `'FsError'`            | `mkdirSync` or `writeFileSync` fails                            |
+| Class                | `_tag`                 | When thrown                                                                |
+| -------------------- | ---------------------- | -------------------------------------------------------------------------- |
+| `PathTraversalError` | `'PathTraversalError'` | A file/folder path or symlink target escapes `basePath` (unless opted out) |
 
 ## License
 

package/dist/lib/cli.d.ts

@@ -0,0 +1,2 @@
+import { Effect } from 'effect';
+export declare const cli: (args: ReadonlyArray<string>) => Effect.Effect<void, import("./errors").PathTraversalError | import("@effect/platform/Error").PlatformError | Error | import("@effect/cli/ValidationError").ValidationError, import("@effect/cli/CliApp").CliApp.Environment>;

package/dist/lib/{src/_commonErrors.d.ts → errors.d.ts}

@@ -7,12 +7,3 @@ export declare class PathTraversalError {
     constructor(path: string);
     toString(): string;
 }
-/**
- * Error type for file system operation failures
- */
-export declare class FsError {
-    readonly message: string;
-    readonly _tag = "FsError";
-    constructor(message: string);
-    toString(): string;
-}

package/dist/lib/fsGenerator.d.ts

@@ -0,0 +1,7 @@
+import { FileSystem, Path } from '@effect/platform';
+import { Effect } from 'effect';
+import { type ParserResult } from './types';
+import { PathTraversalError } from './errors';
+export declare const fileStructureCreator: (items: ParserResult, basePath: string, options?: {
+    allowOutsideSymlinks?: boolean;
+}) => Effect.Effect<void, PathTraversalError | import("@effect/platform/Error").PlatformError, Path.Path | FileSystem.FileSystem>;

package/dist/lib/fsNormalizator.d.ts

@@ -0,0 +1,20 @@
+import { Path } from '@effect/platform';
+import { Effect } from 'effect';
+import { PathTraversalError } from './errors';
+/**
+ * Returns true if the symlink target escapes the base directory.
+ *
+ * @param linkPath string - Path of the symlink relative to project root.
+ * @param target string - The symlink target value.
+ * @param basePath string - Project root (absolute or relative).
+ * @param path Path.Path - Platform path service instance.
+ */
+export declare const isSymlinkOutsideRoot: (linkPath: string, target: string, basePath: string, path: Path.Path) => boolean;
+/**
+ * Safely normalize a user-supplied path against a base directory.
+ * Fails with PathTraversalError if the resolved path escapes the base.
+ *
+ * @param projectPath string - Path relative to project.
+ * @param basePath string - Must be absolute.
+ */
+export declare const resolveProjectPathToBase: (projectPath: string, basePath: string) => Effect.Effect<string, PathTraversalError, Path.Path>;

package/dist/lib/index.d.ts

@@ -0,0 +1,5 @@
+export { fileStructureCreator } from './fsGenerator';
+export { isSymlinkOutsideRoot, resolveProjectPathToBase } from './fsNormalizator';
+export { PathTraversalError } from './errors';
+export type { ParserResult, ParserResultLineItem } from './types';
+export { parserFolderStructure } from './parser';