feat: add ct init for new config repositories #131

Activity

1. github-actions

   added

   triageUnsorted intake — decide in the weekly sweepUnsorted intake — decide in the weekly sweep

   on Aug 20, 2026
2. bwl21

   changed the title [-]Vorschlag: `ct init` für ein neues Config-Repository[/-] [+]feat: add ct init for new config repositories[/+] on Aug 23, 2026
3. bwl21 commented on Aug 24, 2026

   

   bwl21

   on Aug 24, 2026

   Last edited by bwl21

   ContributorAuthor

   More actions

   Follow-up use case: portable, instance-aware process workspace

   The initial repository scaffold in this issue is also the right foundation for reusable domain processes that can be deployed to several ChurchTools instances. The process should live inside an existing repository and be runnable from its own directory without repeating config/state flags:

   cd processes/example-process
   ct plan -e test
   ct plan -e prod

   The normal entry point remains ct.config.ts at the process root. Exceptional multi-stage bootstrap entry points may be selected explicitly with -c configs/....

   Proposed backward-compatible CLI

   Keep the current standard template as the default and add an explicit process template:

   ct init processes/example-process \
     --template process \
     --host https://example.church.tools \
     --env prod \
     --protected \
     --no-git \
     --yes

   --template process is preferable to a one-off --process switch because it leaves room for future templates while preserving ct init [directory] byte-for-byte for existing users. Unknown template names must fail clearly.

   Generic scaffold owned by ct-cli

   <process>/
   ├── ct.config.ts
   ├── ct.envs.json
   ├── .gitignore
   ├── README.md
   ├── blueprint/
   ├── configs/
   └── instances/
       └── example.church.tools/
           ├── ct-state.example.church.tools.json
           ├── backups/
           ├── reference/
           └── reports/
   

   Design decisions for this template:

   • blueprint/ is singular because this workspace represents one reusable domain process; configs/ is plural because it may contain several exceptional entry points. The existing standard template keeps its current blueprints/ and config/ names for compatibility.
   • Portable process definitions stay outside instances/; no generated config contains live ChurchTools IDs.
   • When a host is supplied, its URL hostname determines both instances/<hostname>/ and ct-state.<hostname>.json.
   • ct.envs.json explicitly binds environment, normalized host, hostname-bound state path and protected status.
   • Create the empty host-bound state immediately (version: 1, normalized host, empty resources) so the invariant is reviewable before the first mutating command. Never create a generic ct-state.json for a process environment.
   • Reports, backups and captured live reference data stay below the matching instance directory and are ignored where appropriate; the host-bound state remains intentionally trackable.
   • The generated README documents ct plan -e <env> and ct apply -e <env>, plus explicit -c configs/... for exceptional bootstrap stages.
   • Git initialization remains opt-in. --no-git must never create a nested .git when scaffolding under processes/<name>/ in an existing repository.
   • Preflight all files this template would create and refuse the complete operation before writing anything when one already exists.
   • The implementation remains filesystem-only and fully testable without ChurchTools/network access. No token or credential is written to generated files.

   Deliberate boundaries

   ct init should provide only the generic workspace, instance binding and operational README. Process-specific groups, roles, rulesets, periods, approval criteria and bootstrap stages belong in the consumer repository, not in ct-cli.

   Requiring an explicit --env whenever ct.envs.json exists is a separate engine-wide safety change. This scaffold should warn that -e must not be omitted, but it must not silently change the current single-host fallback established by #22. Related environment/auth ergonomics are discussed in #22 and #117; enforcement should receive its own focused implementation and tests.

   Additional acceptance criteria

   • Existing standard ct init output remains unchanged.
   • Process quickstart works in a new directory and inside an existing Git repository with --no-git.
   • Root-level ct.config.ts loads without -c.
   • Host directory, state filename, state content and environment host cannot name different instances.
   • --protected is reflected in the generated environment profile.
   • No hostless ct-state.json, secret or nested .git is generated.
   • Existing scaffold files are rejected without partial writes.
   • Non-interactive --yes output gives next steps using explicit -e <environment>.
4. bwl21 commented on Aug 24, 2026

   

   bwl21

   on Aug 24, 2026

   ContributorAuthor

   More actions

   Implemented the generic process-workspace extension on the existing #131 development cycle:

   • Branch: feat/131-init (the previous branch/PR was still open and not merged; it was updated from current upstream/main with a merge, not a history rewrite)
   • Draft PR: feat: add ct init scaffolding and process workspaces #139
   • CLI: ct init <directory> --template process --host <url> --env <name> [--protected] --no-git --yes
   • Standard ct init remains the default and keeps its existing scaffold
   • Process template adds root ct.config.ts, blueprint/, configs/, a generated operational README, and instances/<hostname>/
   • The environment and initial empty state share one normalized host and the state path instances/<hostname>/ct-state.<hostname>.json; no generic ct-state.json is created
   • Reports/backups/reference output is instance-local and ignored; credentials and live IDs are never generated
   • Existing scaffold files are rejected before any scaffold write

   Validation: 823 tests passed (5 live tests skipped), 18 focused init/CLI tests passed, typecheck, lint, build, docs-staleness, changed-file Prettier, and git diff --check all passed.

   Still deliberately separate: making --env mandatory whenever ct.envs.json exists. The generated README requires explicit -e <environment>, but this PR does not change the single-instance fallback established by #22. Related environment/auth work remains in #22 and #117; credential bootstrap remains #138.
5. 2000game

   added 3 commits that reference this issue on Aug 24, 2026

   feat(auth): bootstrap a login token from credentials and 2FA (#138) (#…

   ...

   f59bbe5

   fix(init): harden the scaffold, host check and login fall-through

   ...

   4f9247d

   feat: add ct init scaffolding and process workspaces (#139)

   ...

   4e01c03
6. 2000game

   closed this as completedin #139on Aug 25, 2026