space-cadet 9.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 43aad33181b2d51dcdf9a43b797325a90b513b2ea6b9d1aa5774b5c6d3e14fed
+  data.tar.gz: c63367116cb12fc23008af8f0be141b3e4d86db6bd90826c135000898eef5c89
+SHA512:
+  metadata.gz: 50f518864108c2475262cf5931bff2af4cd79205961b7ff935ab187ccf15cfdaa9caa40f835e6926e169cc4f1ca3fdaf284cfea1b4b029598673fcf9de0fc1a2
+  data.tar.gz: 849789bb6f71eb569af79a1d5ed93dbd2c32c1510b8601180fea6ca4129e5d82e2118e8479c3baa2c4e185f1756663046d07fb1959c3634824ba09f5f8d5c9bf

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [9.0.0] - 2026-10-09
+
+### Changed
+
+- **Extracted from space-architect 8.0.0.** The space tool (`Space::Core`,
+  binary `space`) is split back out of
+  [jetpks/space-architect](https://github.com/jetpks/space-architect) into its
+  own repo, gem, and version line — undoing the v1.0.0-era absorption. The gem
+  is `space-cadet`, the binary is `space`, the module stays `Space::Core`, and
+  the version restarts at 9.0.0 (one major above the 8.x line it left).
+- The fish shell integration's internals are renamed to the gem's own identity:
+  `__space_core_*` functions and the `__SPACE_CORE_VERSION__` compat-token
+  placeholder (was `__space_architect_*` / `__SPACE_ARCHITECT_VERSION__`).
+  Re-run `space shell fish install` after upgrading.
+- XDG config/state now live under `~/.config/space-cadet/` and
+  `~/.local/state/space-cadet/` (was `space-architect/`). Run `space init` and
+  migrate any custom `config.yml`/`state.yml` across.
+- The engine's subprocess shell, copy-on-write cloner, and git SCM seam
+  (`Space::Core::Shell`, `Space::Core::Cloner`, `Space::Core::SCM::*`) are
+  vendored into the gem — previously shared with the space-architect monolith's
+  `Space::Src` engine.
+- Dependencies trimmed to exactly what the space tool requires: `async`,
+  `async-process`, `pastel`, `dry-cli`, `dry-monads`.
+
+[9.0.0]: https://github.com/jetpks/space-cadet/blob/main/CHANGELOG.md

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,279 @@
+# Space Cadet 🪐
+
+[![Gem Version](https://badge.fury.io/rb/space-cadet.svg)](https://badge.fury.io/rb/space-cadet)
+
+> **Task-scoped project workspaces — for humans and their agents!** ✨🌌
+
+`space-cadet` is a Ruby gem for **spaces** — task-scoped project workspaces
+that hold repos, notes, and artifacts under one obvious filesystem root. One
+binary, **`space`**, over the `Space::Core` library. It pairs with
+[jetpks/space-architect](https://github.com/jetpks/space-architect) (the
+Architect Loop, which runs on top of spaces) and
+[jetpks/repo-tender](https://github.com/jetpks/repo-tender) (which tends the
+evergreen checkouts spaces provision from).
+
+**Lineage:** this repo is the space tool's original home (the v1.0.0 era); the
+tool was absorbed into space-architect (up to 8.0.0) and is extracted back out
+here as of 9.0.0.
+
+## What's a space? 🪐
+
+A space is just a regular directory with a tiny YAML identity file and room for
+everything a task needs:
+
+```text
+~/architect/spaces/20260531-name-of-space/
+  space.yaml        # identity: id, title, status, repos, notes, tags
+  README.md
+  repos/            # cloned (or copy-on-write'd) repositories
+  notes/            # scratch, prompts, logs
+  architecture/     # project files when the space runs an Architect project
+  build/            # OCI contexts + scratch (build/oci/)
+  tmp/              # workspace-local temp — use this instead of /tmp
+```
+
+Run a command from anywhere inside a space and it just works — `space` walks up
+from `$PWD` until it finds the nearest `space.yaml`. No "current space" state
+to get out of sync; where you *are* is the space you mean. 🧭
+
+## Installation 📦
+
+Add it to your `Gemfile`:
+
+```ruby
+gem "space-cadet"
+```
+
+```bash
+bundle install
+```
+
+Or grab it yourself:
+
+```bash
+gem install space-cadet
+```
+
+The gem is `space-cadet`; it installs one executable, `space`. 🎀
+
+## Quick start 🎀
+
+```sh
+space init                                        # create XDG config + state files
+space new "Name of Space"                         # blast off a new space 🚀
+space new "Name of Space" -r org/repo -r org/lib  # …with repos cloned in (repeat -r)
+space list                                        # see all your spaces
+space show                                        # show the space you're standing in
+
+# Containers (run from inside a space) — a portable, reproducible-by-SHA image of the space
+space pack                                         # render build/oci/ (Dockerfile + entrypoint)
+space build                                        # pack + build & tag <space-id>:<git-sha>
+space run                                          # run it — login shell, auth from your env
+```
+
+## Commands 🌌
+
+```sh
+space init
+space new "Name of Space"
+space new "Name of Space" -r org/repo -r example-tools/alpha -r example-tools/beta
+space list                                   # alias: space ls
+space show 20260531-name-of-space
+space path 20260531-name-of-space
+space current                                # based on $PWD
+space show                                   # based on $PWD
+space status                                 # report: metadata (+ project status when present)
+space status 20260531-name-of-space          # report another space
+space status done                            # set: active | paused | done | archived
+space status 20260531-name-of-space done
+space config set default_provider github.com
+space config set default_organization example-org
+space repo add example-app                   # github.com/example-org/example-app
+space repo add example-tools/alpha example-tools/beta
+space repo add gitlab.com/example-org/api
+space repo resolve example-app example-tools/async
+space repo ls                                # alias: space repos ls
+space use 20260531-name-of-space             # records recent state, prints the path
+space ls --color=always                      # auto | always | never (--colors also accepted)
+```
+
+`space status` is **report-or-set**: with no status keyword (bare, or with just
+a space id) it *reports* the space — its metadata plus a compact project-status
+block when the space declares one, quietly omitted otherwise; pass a status
+keyword (`active`, `paused`, `done`, `archived`) to *set* it instead. 🔁
+
+Repos are passed with a repeatable `-r` flag (`-r org/repo -r org/lib`); the
+comma form (`-r a,b`) works too. Space ids are date-prefixed
+(`20260531-name-of-space`) so they sort naturally, and duplicate names on the
+same day get a counter (`…-name-of-space-2`). 📅
+
+Full command reference: [docs/reference.md](docs/reference.md).
+
+## Containerize a space: `pack` · `build` · `run` 📦
+
+A space is self-describing enough to become a container. `space pack` renders a
+portable OCI build context from the space; `space build` packs and builds it into
+a **reproducible-by-SHA** image; `space run` runs that image with your auth
+injected at runtime and stateful paths bind-mounted back to the host. 🐳
+
+```sh
+space pack                    # render build/oci/ (Dockerfile + entrypoint + ignore file)
+space pack -o /tmp/ctx        # …to a different output directory
+space build                   # pack, then build & tag <space-id>:<git-sha> and :latest
+space run                     # run <space-id>:latest — login shell, auth from your env
+space run architect status    # …or run a one-off command instead of the login shell
+space run --tty               # force an interactive TTY (default: auto-detect)
+```
+
+**What lands in the image.** The context copies the whole space tree (filtered by
+a generated `Dockerfile.dockerignore`) onto a `ruby:4.0.5` base with `git`, the
+Claude Code CLI, and the `space-cadet` gem — installed from the in-space
+`repos/space-cadet` checkout when present (a pinned build), else from
+RubyGems. Secrets never enter the layers: `.env`, `*.key`, `*.pem`, ssh keys,
+`build/`, and `tmp/` are all excluded by the generated ignore file. 🔒
+
+**Reproducible by SHA.** `space build` tags the image `<space-id>:<sha>`, where
+`<sha>` is the space repo's 12-char `HEAD` (suffixed `-dirty` when the tree has
+uncommitted changes), plus a moving `:latest`. Same commit → same tag → same
+image. It drives the `container` CLI, but the output is an ordinary OCI/Docker
+build context, so `docker build -f build/oci/Dockerfile .` (from the space root)
+works just as well.
+
+**Auth stays out of the layers.** `space run` injects only the auth environment
+variables that are actually set — `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`,
+`ANTHROPIC_BASE_URL` — with `-e` at run time, so credentials live in your shell,
+never in the image. 🗝️
+
+**Forwarding payload credentials.** Beyond the always-on auth trio, a space can declare
+`run.env:` in `space.yaml` — a list of host env var names forwarded into the container at
+run time. You can also pass `space run --env VAR` (repeatable) for ad hoc additions. All
+forwarding is bare `-e VAR` passthrough: values never appear in argv, `ps`, or the image.
+A requested-but-unset var warns on stderr instead of silently failing inside the guest.
+
+```yaml
+run:
+  env:                         # run-time: host var names, forwarded as bare -e VAR
+    - FIREWORKS_API_KEY
+    - OPENAI_API_KEY
+```
+
+**Declaring provisioning & persistence** — two optional keys in `space.yaml`:
+
+```yaml
+pack:
+  provision:                 # build-time: relative scripts, baked in by `space build`
+    - scripts/setup-toolchain.sh
+  persist:                   # run-time: absolute guest paths, bind-mounted per run
+    - /root/.claude
+    - /root/.local/state
+```
+
+`provision` scripts must live under the space root and be executable. Each script is
+copied into the image individually (`COPY <script> /space/<script>`) and then invoked
+(`RUN /space/<script>`) **before** the full space tree lands and **before** the gem is
+installed. This ordering is the cache-hygiene guarantee: editing any other space file
+leaves the provision and gem-install layers cached, so a rebuild completes in seconds
+instead of minutes. Scripts must therefore be self-contained — they run with only the
+base system layers and any earlier provision scripts' outputs; they cannot read other
+space files or call `space`. Scripts must have the executable bit set; COPY preserves
+the mode from the build context.
+
+`persist` paths must be absolute; `space run` bind-mounts each one from
+`<space>/.state<path>` on the host (created on first run) so a container's mutable state
+survives across runs. Both are validated at pack time.
+
+## Fish shell integration 🐟
+
+Shells can't let a child process change *their* working directory, so `space`
+ships a small fish wrapper function plus completions (commands, subcommands,
+spaces, statuses, config keys, repo refs). Install into fish's autoloaded
+directories:
+
+```fish
+space shell fish install
+exec fish
+```
+
+After restarting fish (or `exec fish`), `space new "…"` and
+`space use <id>` will `cd` into the selected space once the command succeeds;
+every other command keeps normal CLI behavior. 🚪 The functions and completions
+are written under `~/.config/fish/`, so there's no need to edit `config.fish`.
+For one-off testing without installing:
+
+```fish
+space shell init fish | source
+```
+
+## Configuration ⚙️
+
+Config lives at `~/.config/space-cadet/config.yml` (XDG-aware) and defaults to:
+
+```yaml
+version: 1
+base_dir: ~/architect            # spaces_dir + src_dir hang off this by default
+default_provider: github.com
+default_organization:
+git_clone_protocol: ssh          # ssh | https
+```
+
+Derived defaults: `spaces_dir` → `<base_dir>/spaces`, `src_dir` (evergreen
+checkout root) → `<base_dir>/src`. Override either explicitly. View values with
+`space config show`; set one with `space config set KEY VALUE`. Editable keys:
+`base_dir`, `spaces_dir`, `src_dir`, `default_provider`, `default_organization`,
+`git_clone_protocol`.
+
+## Repos: evergreen, copy-on-write, concurrent ⚡
+
+Repos are added to the current space under `repos/` and tracked in `space.yaml`.
+When an up-to-date evergreen checkout exists at
+`<src_dir>/<host>/<owner>/<name>` (e.g.
+`~/architect/src/github.com/example-org/example-app` — tended by
+[jetpks/repo-tender](https://github.com/jetpks/repo-tender)), `space` copies it
+into the space instead of cloning over the network — a copy-on-write clone on
+APFS. ⚡ Set `src_dir` empty to always clone:
+
+```sh
+space config set src_dir ""
+```
+
+Clone URLs default to SSH (`git@github.com:example-org/example-app.git`); switch
+with `space config set git_clone_protocol https`. Multiple repos passed to
+`space repo add` are fetched **concurrently**, up to five at a time, on fibers —
+no threads, all cooperative. 🧵 After each repo lands, `space` runs `mise trust`
+in it. Each space also gets a workspace-local `tmp/` — use it instead of `/tmp`.
+
+## Embedding 📚
+
+```ruby
+require "space_core"       # config, state, XDG, terminal, git/mise clients,
+                           # the space store — the `space` CLI runs on this alone
+```
+
+## Documentation 📖
+
+- **[Command Reference](docs/reference.md)** — every command, flag, and behavior
+- **[Releasing](docs/RELEASING.md)** — how a release lands
+- **[Changelog](CHANGELOG.md)** — release history
+
+## Development 🛠️
+
+```sh
+bundle install
+bundle exec rake test       # the minitest suite
+bundle exec rake build      # build the gem into pkg/
+bundle exec rake install    # build + install into your user gem home
+```
+
+## Contributing 💝
+
+Bug reports and pull requests are welcome on GitHub at
+[https://github.com/jetpks/space-cadet](https://github.com/jetpks/space-cadet)!
+
+## License 📄
+
+Available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
+
+---
+
+Made with 💖 and fibers 🧵 by Eric

data/exe/space

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+source_gemfile = File.expand_path("../Gemfile", __dir__)
+if File.exist?(source_gemfile)
+  ENV["BUNDLE_GEMFILE"] ||= source_gemfile
+  require "bundler/setup"
+  $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+end
+
+require "space_core"
+
+Space::Core::CLI.run(ARGV, $stdout, $stderr)

data/lib/space_core/atomic_write.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Space::Core
+  module AtomicWrite
+    module_function
+
+    def write(path, content)
+      path = path.to_s
+      dir = File.dirname(path)
+      FileUtils.mkdir_p(dir)
+      tmp_path = File.join(dir, ".#{File.basename(path)}.#{Process.pid}.tmp")
+
+      File.write(tmp_path, content)
+      File.rename(tmp_path, path)
+    ensure
+      FileUtils.rm_f(tmp_path) if defined?(tmp_path) && tmp_path && File.exist?(tmp_path)
+    end
+  end
+end

data/lib/space_core/cli/base_command.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+
+module Space::Core::CLI
+  # Base for every space/architect command. dry-cli (>= 0.7.0) copies a
+  # superclass's options to its subclasses, so the global colour options are
+  # declared once here and inherited everywhere instead of being mixed in per
+  # command. Helpers (terminal/store/render) ride along by inheritance too.
+  #
+  # The `src` binary has its own output-mode system (--plain/--json) and does
+  # NOT inherit from this base.
+  class BaseCommand < Dry::CLI::Command
+    include Helpers
+
+    option :color,  type: :string, default: "auto", desc: "Color output: auto, always, never"
+    option :colors, type: :string, desc: "Alias for --color"
+  end
+end

data/lib/space_core/cli/build.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../oci_packer"
+require_relative "../oci_builder"
+
+module Space::Core::CLI
+class Build < BaseCommand
+  desc "Build (and tag) the OCI image for the current space"
+
+  def call(**opts)
+    setup_terminal(**opts.slice(:color, :colors))
+    handle_errors do
+      result = store.current.bind do |space|
+        out_dir = space.path.join("build", "oci")
+        Space::Core::OciPacker.new(space: space, output_dir: out_dir).generate.bind do
+          Space::Core::OciBuilder.new(space: space, output_dir: out_dir).command
+        end
+      end
+      render(result) do |argv|
+        terminal.say "Building: #{argv.join(' ')}"
+        out.flush
+        Kernel.exec(*argv)
+      end
+    end
+  end
+end
+end

data/lib/space_core/cli/config.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Space::Core::CLI
+module Config
+  class Show < BaseCommand
+    desc "Show current config"
+
+    def call(**opts)
+      setup_terminal(**opts.slice(:color, :colors))
+      handle_errors do
+        rows = Space::Core::Config::EDITABLE_KEYS.map do |key|
+          value = project_config.data[key]
+          [key, value.nil? ? "" : value.to_s]
+        end
+        terminal.say terminal.table(%w[Key Value], rows)
+        CLI.record_outcome(Outcome.new(exit_code: 0))
+      end
+    end
+  end
+
+  class ConfigPath < BaseCommand
+    desc "Print the config file path"
+
+    def call(**opts)
+      setup_terminal(**opts.slice(:color, :colors))
+      handle_errors do
+        terminal.say terminal.path(project_config.path)
+        CLI.record_outcome(Outcome.new(exit_code: 0))
+      end
+    end
+  end
+
+  class Set < BaseCommand
+    desc "Set a config key"
+    argument :key, required: true, desc: "Config key"
+    argument :value, required: true, desc: "Config value"
+
+    def call(key:, value:, **opts)
+      setup_terminal(**opts.slice(:color, :colors))
+      handle_errors do
+        project_config.set(key, value)
+        stored = project_config.data[key]
+        terminal.success "Set #{key}=#{stored.nil? ? '' : stored.to_s}"
+        CLI.record_outcome(Outcome.new(exit_code: 0))
+      end
+    end
+  end
+end
+end

data/lib/space_core/cli/current.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Space::Core::CLI
+class Current < BaseCommand
+  desc "Show the current space"
+
+  def call(**opts)
+    setup_terminal(**opts.slice(:color, :colors))
+    render(store.find) do |space|
+      terminal.say space.id.to_s
+      terminal.say terminal.path(space.path)
+      CLI.record_outcome(Outcome.new(exit_code: 0))
+    end
+  end
+end
+end