@git.zone/cli 6.6.1 → 6.7.1

package/readme.hints.md

@@ -1,596 +0,0 @@
-# Gitzone CLI - Development Hints
-
-- the cli of the git.zone project.
-
-## Project Overview
-
-Gitzone CLI (`@git.zone/cli`) is a comprehensive toolbelt for streamlining local development cycles. It provides utilities for:
-
-- Project initialization and templating (via smartscaf)
-- Code formatting and standardization
-- Version control and commit management
-- Docker and CI/CD integration
-- Meta project management
-
-## Architecture
-
-### Core Structure
-
-- Main CLI entry: `cli.ts` / `cli.child.ts`
-- Modular architecture with separate modules in `ts/mod_*` directories
-- Each module handles specific functionality (format, commit, docker, etc.)
-- Extensive use of plugins pattern via `plugins.ts` files
-
-### Configuration Management
-
-- Uses `.smartconfig.json` for tool configuration
-- CLI settings live under the `@git.zone/cli` namespace
-- Agent and non-interactive defaults now belong under `@git.zone/cli.cli`
-- Project type, module metadata, release settings, commit defaults, and format settings live in the same file
-
-### Format Module (`mod_format`) - SIGNIFICANTLY ENHANCED
-
-The format module is responsible for project standardization:
-
-#### Current Modules:
-
-1. **cleanup** - Removes obsolete files (yarn.lock, tslint.json, etc.)
-2. **copy** - File copying with glob patterns (fully implemented)
-3. **gitignore** - Creates/updates .gitignore from templates
-4. **license** - Checks dependency licenses for compatibility
-5. **smartconfig** - Manages project metadata and configuration
-6. **packagejson** - Formats and updates package.json
-7. **prettier** - Applies code formatting with batching
-8. **readme** - Ensures readme files exist
-9. **templates** - Updates project templates based on type
-10. **tsconfig** - Formats TypeScript configuration
-
-#### Execution Order (Dependency-Based):
-
-- Modules are now executed in parallel groups based on dependencies
-- Independent modules run concurrently for better performance
-- Dependency analyzer ensures correct execution order
-
-### New Architecture Features
-
-1. **BaseFormatter Pattern**: All formatters extend abstract BaseFormatter class
-2. **FormatContext**: Central state management across all modules
-3. **FormatPlanner**: Implements plan → action workflow
-4. **RollbackManager**: Full backup/restore capabilities
-5. **ChangeCache**: Tracks file changes to optimize performance
-6. **DependencyAnalyzer**: Manages module execution order
-7. **DiffReporter**: Generates diff views for changes
-8. **FormatStats**: Comprehensive execution statistics
-
-### Key Patterns
-
-1. **Plugin Architecture**: All dependencies imported through `plugins.ts` files
-2. **Streaming**: Uses smartstream for file processing
-3. **Interactive Prompts**: smartinteract for user input
-4. **Enhanced Error Handling**: Comprehensive try-catch with automatic rollback
-5. **Template System**: Templates handled by smartscaf, not directly by gitzone
-6. **Type Safety**: Full TypeScript with interfaces and type definitions
-
-### Important Notes
-
-- `.nogit/` directory used for temporary/untracked files, backups, and cache
-- `.nogit/gitzone-backups/` stores format operation backups
-- `.nogit/gitzone-cache/` stores file change cache
-- Templates are managed by smartscaf - improvements should be made there
-- License checking configurable with exceptions support
-- All features implemented: `ensureDependency`, copy module, etc.
-
-## Recent Improvements (Completed)
-
-1. **Plan → Action Workflow**: Shows changes before applying them
-2. **Rollback Mechanism**: Full backup and restore on failures
-3. **Enhanced Configuration**: Granular control via `.smartconfig.json`
-4. **Better Error Handling**: Detailed errors with recovery options
-5. **Performance Optimizations**: Parallel execution and caching
-6. **Reporting**: Diff views, statistics, verbose logging
-7. **Architecture**: Clean separation of concerns with new classes
-8. **Split Commit/Release Workflows**: `commit` creates source commits; `release` owns versioning, tags, and artifact publishing
-
-### Commit/Release Workflow Refactor (Latest)
-
-The commit module no longer bumps versions, creates tags, or publishes packages. Release work now belongs to `gitzone release`:
-
-**Changes:**
-
-- `gitzone commit` analyzes changes, updates `changelog.md` `Pending`, commits, and optionally pushes.
-- `gitzone release` reads `Pending`, bumps versions, moves changelog entries into a version section, tags, pushes, and publishes configured artifacts.
-- Commit workflow steps are configured in `.smartconfig.json` under `@git.zone/cli.commit.steps`.
-- Smartconfig schema versioning lives at `@git.zone/cli.schemaVersion`; run `gitzone config migrate <version>` for targeted migrations.
-- Release publishing is target-based under `@git.zone/cli.release.targets`.
-- NPM registries only live under `@git.zone/cli.release.targets.npm.registries`.
-
-### Exact artifact release journal schemas 1 and 2
-
-Every release that reaches final publication atomically installs
-canonical state below the Git common directory at
-`gitzone/releases/v1/v<version>/`. npm releases contain exactly one
-`package.tgz`; the journal binds that file's package identity, byte length,
-SHA-1, SHA-256, SHA-512 integrity, release commit, annotated tag object, hashed
-Git destination, registry list, and target attempts. The state is deliberately
-outside the worktree so build cleanliness checks do not conflict with durable
-recovery.
-
-Non-Docker releases retain journal schema 1 byte-for-byte. Docker releases use
-schema 2 in the same storage tree. Before confirmation or source mutation,
-GitZone validates the deterministic tSDocker request against the source commit;
-it validates the final release-commit request again immediately before journal
-installation. Schema 2 then persists immutable candidate and OCI graph evidence
-plus the complete ordered promotion set before Git or npm publication.
-Each destination promotion is write-ahead claimed, remotely reconciled by exact
-digest, and append-only. Positive destination conflict is terminal. Candidate
-cleanup of a qualified result is journaled only after every promotion is
-verified, except that a terminal qualification destination conflict permits
-cleanup while Git/npm stay blocked. Completed Docker state is terminal.
-
-Journal writes are fsynced same-directory replacements under the shared
-atomic-mkdir lock and require the caller's exact prior revision. Transactions
-may update target attempts and completion state but cannot alter release,
-artifact, destination, or target identity. A malformed, noncanonical, future,
-or manually reformatted journal fails closed.
-
-Selected Git publication requires a canonical remote name and validates its
-single resolved push URL before remote contact, including during planning.
-Embedded HTTP(S) credentials, passwords, parameters, and unsupported protocols
-fail closed. Git publication then probes the exact branch, annotated tag
-object, and peeled tag commit before and after an atomic leased push. npm publication always uses the
-stored tarball and verifies each public registry anonymously with redirects
-disabled. Verification covers metadata identity, integrity and shasum, bounded
-downloaded bytes, SHA-256, and the `latest` dist-tag.
-
-`gitzone release inspect [version]` is read-only. `gitzone release resume
-<version>` rejects fresh-release overrides and never rebuilds or repacks the npm
-artifact. It also rejects changed journaled configuration. A nonterminal
-schema-2 resume canonical-compares the current request, requires matching
-project-local tSDocker package and binary versions `>=3.5.1` plus all required
-protocol-v1 capabilities, and validates the journaled request before any
-recovery. Additional future capabilities are accepted. A completed schema-2
-journal trusts terminal cleanup evidence without requiring the old candidate or
-current Docker configuration. A target left in `publishing` state requires the
-exact recorded attempt ID and independent proof that its process stopped; no
-timeout or PID guess reclaims publication authority. Recovery reclaims only
-private request files bound to that exact retired attempt before a CAS transition
-claims a fresh owner. Promotion recovery probes exact digest state before
-retrying and retains the old owner on inconclusive evidence. A tSDocker
-`RECOVERY_REQUIRED` qualification has no completed evidence, so its exact
-recovered owner removes only the incomplete `preparing` record before a fresh
-qualification attempt. Final qualified-candidate cleanup remains ordered after
-promotion.
-
-Recovery begins only after atomic journal installation. Local
-version, changelog, commit, tag, build, and pack failures before that point, as
-well as the pre-release `--merge` integration push, require explicit operator
-reconciliation; they are not represented as publication attempts.
-
-Schema 1 supports Git and public npm; npm publication requires resolved pnpm
-11.25.0, 12.1.0, or 12.3.4 and its qualified pack/publish contract, while
-Git-only journals do not. Schema 2 adds Docker qualification,
-ordered promotion, and cleanup. Docker releases
-cannot use `--merge` because its pre-release push would violate qualification
-ordering, and `release.targets.docker.noBuild` must remain false because
-qualification always builds. Private npm cannot be anonymously verified.
-Legacy tag-triggered `npmci npm publish` jobs must be removed because they
-bypass journal ownership.
-
-**Benefits:**
-
-- Commit is safer and has no publishing side effects.
-- Multiple source commits can accumulate into one release via `Pending`.
-- Durable target states distinguish pending, publishing, verified, failed,
-  conflicting, and skipped publication while retaining exact attempt evidence.
-
-### Auto-Accept Flag for Commits
-
-The commit module now supports `-y/--yes` flag for non-interactive commits:
-
-**Usage:**
-
-- `gitzone commit -y` - Auto-accepts AI recommendations without prompts
-- `gitzone commit -yp` - Auto-accepts and pushes to origin
-- Separate `-p/--push` flag controls push behavior
-
-**Implementation:**
-
-- Creates AnswerBucket programmatically when `-y` flag detected
-- Preserves all UI output for transparency
-- Fully backward compatible with interactive mode
-- CI/CD friendly for automated workflows
-
-## Destructive Command Policy
-
-`gitzone docker prune` used to be a single line:
-
-```ts
-await smartshellInstance.exec(`docker system prune -a -f --volumes`);
-```
-
-Machine-wide, forced, volumes included, behind a command described as "Run
-Docker-related maintenance tasks". On a shared host that is unrecoverable data
-loss with no prompt. It is now allowlist-scoped (`classes.dockerpruner.ts`).
-
-The policy every destructive path in this CLI should follow:
-
-1. **Scope by positive evidence, never by absence.** Start from an allowlist —
-   a label, a registry claim, an explicit target — not from "everything unused".
-   `DockerPruner.isToolOwned` requires _both_ `git.zone.tool` (provenance) and
-   `git.zone.safe-to-prune=true` (consent); either alone is insufficient.
-2. **Report by default, destroy behind `--apply`.**
-3. **Persisted data needs its own gate.** Volumes and data directories are
-   excluded unless separately requested, and additionally require a typed `yes`
-   or `--yes`. The gate is enforced before the output branches so JSON mode
-   cannot bypass it.
-4. **Re-verify at apply time** and throw on drift rather than proceeding.
-5. **Ambiguity excludes.** Unprovable ownership means skip, never remove.
-6. **The name must match the blast radius.** A destructive command described as
-   "cleanup" or "maintenance" is the actual root cause of accidental invocation.
-
-Known remaining gaps are listed in `readme.plan.md`.
-
-## Services Module (`mod_services`) — Cleanup Design
-
-### Why data accumulated
-
-`gitzone services clean` historically failed for service data written by a
-container uid. A recursive delete run as the invoking user removed only the
-part of the tree it owned. For MongoDB the result was a half-deleted WiredTiger
-dataset that crash-looped on the next start (`WiredTigerHS.wt file is corrupted
-or missing`), kept alive indefinitely by `restart: unless-stopped`. Users hit a
-failing `clean`, gave up, and the data stayed. This was the root cause of
-multi-GB accumulation, not a missing feature.
-
-`DockerContainer.removeDataDirectory` fixes it by persisting a deletion intent
-and atomically renaming the canonical path to a tokenized quarantine before any
-recursive delete. Native deletion runs there; if the quarantine survives, a
-short-lived root container mounts only that directory. The helper uses
-shell-free Docker argv, stopped creation, exact configuration and label
-inspection, and an immutable-ID fence before execution or cleanup. Interrupted
-cleanup resumes the recorded quarantine, so partial work is never mistaken for
-a usable canonical dataset.
-
-### Identifying tool-owned resources
-
-Follows the `git.zone.*` label convention already established by
-`@git.zone/tsdocker`. Containers created by `gitzone services` carry:
-
-```text
-git.zone.tool=gitzone-services
-git.zone.service=mongodb|objectstorage|elasticsearch
-git.zone.project-path=<abs path>
-git.zone.data-path=<abs path>
-git.zone.safe-to-prune=true
-```
-
-Data directories are additionally claimed by a marker at
-`<project>/.nogit/.gitzone-services.json`. The marker deliberately lives outside
-the bind-mounted directory so it can never confuse mongod, ObjectStorage or
-Elasticsearch at runtime.
-
-Nothing is ever matched by image or by bare name pattern. MongoDB and
-Elasticsearch containers predating labels are identified only when exactly one
-registry entry claims their name. ObjectStorage always requires exact labels.
-
-### Prune safety model (`classes.servicepruner.ts`)
-
-Mirrors `TsDockerPruner`: build a plan, print it, and mutate only on `--apply`
-with every item re-verified immediately before removal.
-
-Projects classify as `live`, `stale`, `orphaned`, or `unknown`. Only `stale` and
-`orphaned` are candidates; `unknown` never is. Ambiguity must _tighten_ the
-decision — a container name claimed by two projects forces both to `unknown`,
-because an unattributable container also means "no container is running" cannot
-be proven. Getting this backwards initially made 1.18 GB look reclaimable when
-it was not.
-
-Invariants, enforced at plan time and again at apply time:
-
-- A data directory is never removed while any running container bind-mounts it
-  or an overlapping path (`helpers.pathsOverlap`).
-- A path must match `<project>/.nogit/{mongodata,objectstoragedata,esdata}` exactly
-  (`isSafeServiceDataPath`); this is an allowlist, checked after resolution.
-- Ownership must be proven by marker or registry entry. ObjectStorage is
-  stricter: an exact marker entry is required for deletion, but an exactly
-  label-owned canonical container can repair a missing marker before removal.
-- Data-directory staleness is re-checked at apply time. Container removal
-  separately rechecks immutable identity, running state, ownership, and legacy
-  classification before mutation.
-- An unreachable Docker daemon disables container, data, and registry
-  reclamation, so ambiguity never reads as absence.
-
-Legacy `.nogit/miniodata` is deliberately outside the allowlist. Marker
-migration retains that path with `safeToPrune: false`; registry migration
-retains the legacy container reference separately. The service and general
-Docker pruners reject legacy MinIO containers, and service prune rejects
-bind-operation helpers again at apply time.
-
-### ObjectStorage migration and lifecycle
-
-`objectstorage` is the canonical service identifier and `s3` is its user-facing
-alias. Persisted `minio` and `s3` entries migrate to the same canonical flat
-array value because `@git.zone/cli.services` remains a tsdeploy capability
-input. New CLI input does not accept the provider name `minio`.
-
-The active container is `<project>-objectstorage`, its data path is
-`.nogit/objectstoragedata`, and its image is pinned by manifest-list digest.
-Ports `9000` and `3000` are published as the configured API and UI ports on
-`127.0.0.1`. `S3_ADMIN_PASSWORD`, `S3_REGION`, and `S3_UI_PORT` are
-ObjectStorage-specific runtime fields. Existing generic fields such as
-`S3_ENDPOINT`, `S3_HOST`, and `S3_USESSL` are preserved rather than silently
-rewritten; internal reconciliation always targets loopback explicitly.
-
-Startup first rejects legacy `<project>-minio` containers, registry-retained
-alternate legacy names, and `.nogit/miniodata`, then proves exact labels on any
-canonical same-name container. Exact container proof can repair a missing valid
-data marker; invalid or foreign markers remain blocking. Drift reconciliation
-covers the complete runtime contract, including
-the exact set of `OBJST_*` and `UI_PORT` controls while allowing unrelated image
-environment, and all subsequent Docker mutations use the discovered immutable
-ID. A shared 30-second deadline bounds Docker setup, `/readyz`, authenticated
-bucket lookup/creation, and verification. SmartBucket provides its own bounded,
-idempotent client cleanup. A pre-existing ID enters rollback only after `docker
-start` succeeds; an uncertain pre-existing start remains adoptable because
-state inspection cannot prove which concurrent invocation caused the transition.
-
-The v2 marker and global registry schemas separate canonical ObjectStorage from
-legacy MinIO evidence. Legacy evidence is detection-only: never activate it,
-reinterpret its disk data, pass it to lifecycle methods, or make it reclaimable.
-Migration validates every selected store before the first write, then revalidates
-each store at its own apply boundary. Closed-schema selection, marker, and
-registry state rejects malformed, foreign, conflicting, or future shapes.
-Runtime config validates known fields while preserving unknown fields. The
-global registry uses a shared atomic-mkdir transaction lock, fresh raw reads,
-fsynced same-directory
-replacement writes, and compare-delete for unregister operations. Lock ownership
-is token-checked and release first renames to an invocation tombstone. Stale locks
-are never broken automatically; the error reports the exact lock path for manual
-inspection after the recorded process is known to be gone.
-
-The same lock primitive protects runtime-config migration and saves, marker
-migration and ownership recording, and each service's start/delete data-path
-critical section. Runtime config saves compare the bytes loaded by that instance
-with the current file before replacement, so a stale command cannot overwrite a
-newer port or credential change. Marker writers re-read inside the lock and merge
-claims. Start and stop refresh config inside a global per-project/service lock.
-Data deletion rechecks labeled stopped containers and all configured mounts
-inside that lock; a preserved stopped container blocks its project's data from
-becoming reclaimable. Before recursive deletion, an exact persisted intent
-atomically moves the canonical directory to a tokenized quarantine. Interrupted
-or partial cleanup resumes only that recorded path and cannot leave a corrupt
-canonical dataset. Every service startup rejects a pending deletion intent so a
-fresh canonical directory cannot strand quarantined data.
-
-Bind-operation helpers use one deterministic Docker name per host target as an
-atomic helper-level lock. Each create adds a random invocation label and a
-stable ownership-spec label. Uncertain creates are polled within the rollback
-deadline and may be removed only when the invocation label matches. A later
-operation may remove an old stopped canonical helper by non-forced immutable-ID
-removal; fresh, running, or noncanonical occupants fail closed. This lock covers
-the root helper operations, not the entire service start/clean command.
-
-### MongoDB auth modes
-
-Default is authenticated, single-node replica set with a keyfile.
-`gitzone services auth mongodb off` opts into a no-auth instance for runtimes
-that cannot complete a SCRAM handshake over `node:crypto` (Deno). In that mode
-the port is published on `127.0.0.1` only — publishing scope is the real
-exposure control, since `--bind_ip_all` binds inside the container netns — and a
-non-local `MONGODB_HOST` is refused. `MONGO_INITDB_ROOT_*` must be omitted in
-no-auth mode because the official entrypoint turns them into `--auth`.
-
-Re-enabling auth over data created without it finds no root user, because
-`MONGO_INITDB_ROOT_*` only applies to an empty dbpath. `ensureMongoRootUser`
-bootstraps it through MongoDB's localhost exception, which by design only works
-while zero users exist and therefore cannot escalate anything.
-
-### Per-service configuration lives in a sibling key
-
-`@git.zone/cli.serviceOptions` holds committed per-service configuration
-(currently `mongodb.auth`). It is a **sibling** of `services`, not a richer
-`services` value, because widening `services` breaks deployments — see the
-coupling note below. Verified empirically: a mixed array `[{name:'mongodb'},…]`
-and an object-shaped `services` both make TsDeploy throw.
-
-Precedence is `.smartconfig.json` declaration → `.nogit/env.json` local value →
-default enabled. The declaration wins so a fresh checkout is reproducible; the
-local fallback keeps projects configured under 2.24.0 working. Malformed
-declarations are ignored rather than throwing, and ignoring always resolves to
-the safe default. `setMongoAuthEnabled` writes both files so they cannot drift.
-
-An older CLI ignores `serviceOptions` entirely and gets auth-enabled MongoDB —
-the failure direction is toward the secure default.
-
-### Coupling: services config is a deployment input
-
-`@git.zone/cli.services` is read by `@git.zone/tsdeploy`
-(`deriveRequiredCapabilities` in `classes.cloudlydeployment.ts`) to derive a
-workload's `requiredCapabilities`. It **throws** unless the value is a flat array
-of unique, non-empty, lowercase canonical strings. Never add sub-keys under it
-and never change the persisted names — turning it into an object would fail real
-deployments. Any new services configuration belongs in `.nogit/env.json` or a
-sibling key.
-
-## Development Tips
-
-- Always check readme.plan.md for ongoing improvement plans
-- Use `.smartconfig.json` for any new configuration options
-- Keep modules focused and single-purpose
-- Maintain the existing plugin pattern for dependencies
-- Test format operations on sample projects before deploying
-- Consider backward compatibility when changing configuration structure
-- Use BaseFormatter pattern for new format modules
-- Leverage FormatContext for cross-module state sharing
-
-## Configuration Examples
-
-```json
-{
-  "@git.zone/cli": {
-    "cli": {
-      "interactive": true,
-      "output": "human",
-      "checkUpdates": true
-    },
-    "format": {
-      "interactive": true,
-      "showStats": true,
-      "modules": {
-        "skip": ["prettier"],
-        "only": []
-      }
-    }
-  }
-}
-```
-
-## CLI Usage
-
-### Commit Commands
-
-```bash
-# Interactive commit (default)
-gitzone commit
-
-# Read-only recommendation
-gitzone commit recommend --json
-
-# Auto-accept AI recommendations (no prompts)
-gitzone commit -y
-gitzone commit --yes
-
-# Auto-accept and push to origin
-gitzone commit -yp
-gitzone commit -y -p
-gitzone commit --yes --push
-
-# Run format before commit
-gitzone commit --format
-```
-
-### Format Commands
-
-```bash
-# Basic format
-gitzone format
-
-# Read-only JSON plan
-gitzone format plan --json
-
-# CI-friendly check, exits non-zero when changes or validator errors remain
-gitzone format check
-
-# Dry run to preview changes
-gitzone format --dry-run
-
-# Limit formatter modules
-gitzone format --only prettier,packagejson
-gitzone format --skip license
-
-# Non-interactive apply
-gitzone format --write --yes
-
-# Deterministic format first, opencode for remaining issues
-gitzone format fix
-
-# Plan only (no execution)
-gitzone format --plan-only
-
-# Save plan for later
-gitzone format --save-plan format.json
-
-# Execute saved plan
-gitzone format --from-plan format.json
-
-# Verbose mode
-gitzone format --verbose
-
-# Detailed diff views
-gitzone format --detailed
-
-# Inspect config for agents and scripts
-gitzone config show --json
-gitzone config set cli.output json
-gitzone config get release.targets.npm.accessLevel
-```
-
-## Common Issues (Now Resolved)
-
-1. ✅ Format operations are now reversible with rollback
-2. ✅ Enhanced error messages with recovery suggestions
-3. ✅ All modules fully implemented (including copy)
-4. ✅ Dry-run capability available
-5. ✅ Extensive configuration options available
-
-## Future Considerations
-
-- Plugin system for custom formatters
-- Git hooks integration for pre-commit formatting
-- Advanced UI with interactive configuration
-- Format presets for common scenarios
-- Performance benchmarking tools
-
-## API Changes
-
-### Smartfile v13 Migration (Latest - Completed)
-
-The project has been fully migrated from @push.rocks/smartfile v11 to v13, which introduced a major breaking change where filesystem operations were split into two separate packages:
-
-**Packages:**
-
-- `@push.rocks/smartfile` v13.1.3 - File representation classes (SmartFile, StreamFile, VirtualDirectory)
-- `@push.rocks/smartfs` v1.6.0 - Filesystem operations (read, write, exists, stat, etc.)
-
-**Key API Changes:**
-
-1. **File Reading**:
-   - Old: `plugins.smartfile.fs.toStringSync(path)` or `plugins.smartfile.fs.toObjectSync(path)`
-   - New: `await plugins.smartfs.file(path).encoding('utf8').read()` + JSON.parse if needed
-   - Important: `read()` returns `string | Buffer` - use `as string` type assertion when encoding is set
-
-2. **File Writing**:
-   - Old: `plugins.smartfile.memory.toFs(content, path)` or `plugins.smartfile.memory.toFsSync(content, path)`
-   - New: `await plugins.smartfs.file(path).encoding('utf8').write(content)`
-
-3. **File Existence**:
-   - Old: `plugins.smartfile.fs.fileExists(path)` or `plugins.smartfile.fs.fileExistsSync(path)`
-   - New: `await plugins.smartfs.file(path).exists()`
-
-4. **Directory Operations**:
-   - Old: `plugins.smartfile.fs.ensureDir(path)`
-   - New: `await plugins.smartfs.directory(path).recursive().create()`
-   - Old: `plugins.smartfile.fs.remove(path)`
-   - New: `await plugins.smartfs.directory(path).recursive().delete()` or `await plugins.smartfs.file(path).delete()`
-
-5. **Directory Listing**:
-   - Old: `plugins.smartfile.fs.listFolders(path)` or `plugins.smartfile.fs.listFoldersSync(path)`
-   - New: `await plugins.smartfs.directory(path).list()` then filter by `stats.isDirectory`
-   - Note: `list()` returns `IDirectoryEntry[]` with `path` and `name` properties - use `stat()` to check if directory
-
-6. **File Stats**:
-   - Old: `stats.isDirectory()` (method)
-   - New: `stats.isDirectory` (boolean property)
-   - Old: `stats.mtimeMs`
-   - New: `stats.mtime.getTime()`
-
-7. **SmartFile Factory**:
-   - Old: Direct SmartFile instantiation
-   - New: `plugins.smartfile.SmartFileFactory.nodeFs()` then factory methods
-
-**Migration Pattern:**
-All sync methods must become async. Functions that were previously synchronous (like `getProjectName()`) now return `Promise<T>` and must be awaited.
-
-**Affected Modules:**
-
-- ts/mod_format/\* (largest area - 15+ files)
-- ts/mod_commit/\* and ts/mod_release/\* (commit/release workflows)
-- ts/mod_services/\* (configuration management)
-- ts/mod_meta/\* (meta repository management)
-- ts/mod_standard/\* (template listing)
-- ts/mod_template/\* (template operations)
-
-**Previous API Changes:**
-
-- smartnpm requires instance creation: `new NpmRegistry()`
-- Type imports use `import type` for proper verbatim module syntax