space-architect 2.0.0 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5828b73d6d58a9d14547e9d8be9e7f8a734212c7e7356a01149c4c9cbeadd9c
-  data.tar.gz: a8c75e611270a1ff40f0cfd55753549d6972ae2d6af4999695b688f35942bb88
+  metadata.gz: 7251e017d780c7fc4accd3d4ee367d2b5063bb4d0c1692c0c69bc81a228c9fa7
+  data.tar.gz: ad25da0cf6025716953685d7483e86898368170967a29465625335337f8427a3
 SHA512:
-  metadata.gz: a9ff6975fce076eb36bfcd398129551182662830c1f433dfd3d57c375fa32d0ed8b547c46aca5d3959742a454c7523335109ab3ef5d406c8bd5ea6221797b8f4
-  data.tar.gz: 9f20d1e71cc27260fa7e8f1c3090c95b670ae9edea2d9394510e18ddfb6d9543c15655a2ecc2532cd3ba73e4f0250b24a55e00b838b475d64d9331f518d197dd
+  metadata.gz: baf43e94bcd35987bb133f3958709bfc4083851732ed2d47ef72b25b92e042cfb72c2594f1067189e9581c554140cd2d6145dc7d607f9137931250522ba445dc
+  data.tar.gz: 0ecd90d05ea7dc4c3832fea90f7af76650b1c8279ced9e7e48242b825aaeef8e7291d6dc9b4dacd6bfac00ad647ecca887a2f27abb3823181287885ccede7210

data/CHANGELOG.md

@@ -5,6 +5,41 @@ 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).
 
+## [2.0.2] - 2026-07-01
+
+### Added
+
+- **Declarative runtime env forwarding for `space run`.** A space can declare
+  `run.env:` in `space.yaml` — a list of host env vars forwarded into the
+  container as bare `-e VAR` passthrough (value never lands in argv/`ps`), on top
+  of the always-on substrate auth vars. `space run --env VAR` (repeatable) adds
+  more ad hoc. A requested-but-unset var warns on stderr instead of failing
+  opaquely in-guest. This lets credentialed payloads (e.g. a Fireworks/OpenAI key)
+  run via a plain `space run <cmd>` with no wall of flags, without baking secrets.
+
+## [2.0.1] - 2026-07-01
+
+Fast-follow completing the `pack.persist:` story from 2.0.0.
+
+### Added
+
+- **Seed-on-empty for `pack.persist:`.** Content baked at a persisted path now
+  survives a first-run empty bind mount. `space pack` snapshots each persisted
+  dir to a `/opt/space-seed<path>` sidecar after provisioning, and the entrypoint
+  restores an empty mount from its seed on first run only (a non-empty mount
+  keeps its evolving state). Previously the empty host mount shadowed the baked
+  content — e.g. a provisioned `~/.hermes/config.yaml` was hidden once
+  `/root/.hermes` was persisted. Template-only; a space with no `pack.persist:`
+  renders an identical Dockerfile and entrypoint.
+
+### Fixed
+
+- **First-run boot on bind-mount-root-restricted runtimes.** The seed restore
+  tolerates a benign copy failure (`2>/dev/null || true`) so that on runtimes
+  where the persisted path is a bind mount whose root rejects utime updates
+  (virtiofs under Apple `container`), the entrypoint's `set -e` no longer turns a
+  cosmetic `cp` EPERM into a fatal abort before the payload execs.
+
 ## [2.0.0] - 2026-07-01
 
 A ground-up release across four fronts:
@@ -293,6 +328,8 @@ the **BREAKING** items under Changed. The repository is now a monorepo; the
   lanes, worktrees, and headless `claude -p` dispatch, with variant sets and the
   claude-code and opencode harnesses.
 
+[2.0.2]: https://github.com/jetpks/space-architect/compare/v2.0.1...v2.0.2
+[2.0.1]: https://github.com/jetpks/space-architect/compare/v2.0.0...v2.0.1
 [2.0.0]: https://github.com/jetpks/space-architect/compare/v1.3.0...v2.0.0
 [1.3.0]: https://github.com/jetpks/space-architect/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/jetpks/space-architect/compare/v1.1.0...v1.2.0

data/README.md

@@ -158,6 +158,19 @@ variables that are actually set — `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKE
 `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
@@ -169,10 +182,19 @@ pack:
     - /root/.local/state
 ```
 
-`provision` scripts must live under the space root and run as `RUN /space/<script>`
-while the image builds. `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.
+`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 `architect`/`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.
 
 Like everything else, these are reachable as `architect space pack|build|run`
 from inside a project.

data/lib/space_core/cli/run.rb

@@ -9,21 +9,35 @@ class Run < BaseCommand
 
   argument :command, type: :array, required: false, desc: "Command to run in the container (default: login shell)"
   option :tty, type: :boolean, default: nil, desc: "Force interactive TTY (default: auto-detect)"
+  option :env, type: :array, desc: "Host env var to forward into the container (repeatable; adds to run.env)"
 
-  def call(command: [], tty: nil, **opts)
+  def call(command: [], tty: nil, env: [], **opts)
     setup_terminal(**opts.slice(:color, :colors))
     handle_errors do
       result = store.current.bind do |space|
-        runner = Space::Core::OciRunner.new(space: space, interactive: tty.nil? ? CLI.tty?(out) : tty)
+        runner = Space::Core::OciRunner.new(
+          space: space, interactive: tty.nil? ? CLI.tty?(out) : tty, env_vars: env
+        )
         runner.command(command).fmap { |argv| { argv: argv, runner: runner } }
       end
       render(result) do |r|
         r[:runner].host_dirs.each { |d| FileUtils.mkdir_p(d) }
+        warn_missing_env(r[:runner].missing_env)
         terminal.say "Running: #{r[:argv].join(' ')}"
         out.flush # Kernel.exec replaces the process without flushing buffered IO
         Kernel.exec(*r[:argv])
       end
     end
   end
+
+  private
+
+  # A requested var absent from the host env is almost always a forgotten export;
+  # forwarding silently omits it and the payload fails opaquely in-guest. Warn, don't fail.
+  def warn_missing_env(missing)
+    return if missing.empty?
+
+    terminal.error("Warning: requested env not set on host, not forwarded: #{missing.join(', ')}")
+  end
 end
 end

data/lib/space_core/oci_packer.rb

@@ -84,6 +84,10 @@ module Space::Core
       [entrypoint_content].pack("m0")
     end
 
+    def local_space_architect?
+      space.path.join("repos/space-architect").directory?
+    end
+
     def render_template(name)
       template_path = TEMPLATE_DIR.join(name)
       ERB.new(template_path.read, trim_mode: "-").result(binding)

data/lib/space_core/oci_runner.rb

@@ -7,12 +7,15 @@ module Space::Core
   class OciRunner
     include Dry::Monads[:result]
 
+    # Always-forwarded substrate auth (the in-image architect/claude reach for these).
+    # Payload-specific vars are declared per-space via `run.env:` or the --env flag.
     AUTH_ENV = %w[ANTHROPIC_API_KEY CLAUDE_CODE_OAUTH_TOKEN ANTHROPIC_BASE_URL].freeze
 
-    def initialize(space:, env: ENV.to_h, interactive: true)
+    def initialize(space:, env: ENV.to_h, interactive: true, env_vars: [])
       @space = space
       @env = env
       @interactive = interactive
+      @env_vars = (space.run_env + Array(env_vars)).map(&:to_s)
     end
 
     def image
@@ -36,7 +39,7 @@ module Space::Core
       argv = [
         "container", "run", "--rm",
         *(@interactive ? ["-i", "-t"] : []),
-        *auth_flags,
+        *env_flags,
         *mount_flags,
         image,
         *extra
@@ -44,17 +47,30 @@ module Space::Core
       Success(argv)
     end
 
+    # Explicitly-requested vars (run.env: + --env) that are unset/empty in the host
+    # env, so the caller can warn — silence here would let a missing key fail opaquely
+    # inside the guest. AUTH_ENV is opportunistic and intentionally excluded.
+    def missing_env
+      @env_vars.uniq.reject { |var| present?(var) }
+    end
+
     private
 
     attr_reader :space, :env, :interactive
 
-    def auth_flags
-      AUTH_ENV.each_with_object([]) do |var, flags|
-        val = env[var]
-        flags.push("-e", var) if val && !val.empty?
+    # Bare `-e VAR` passthrough (no =value on the command line, so the secret never
+    # lands in argv/ps): substrate auth first, then the space's declared payload vars.
+    def env_flags
+      (AUTH_ENV + @env_vars).uniq.each_with_object([]) do |var, flags|
+        flags.push("-e", var) if present?(var)
       end
     end
 
+    def present?(var)
+      val = env[var]
+      val && !val.empty?
+    end
+
     def mount_flags
       mounts.each_with_object([]) do |(host, guest), flags|
         flags.push("-v", "#{host}:#{guest}")

data/lib/space_core/space.rb

@@ -56,6 +56,12 @@ module Space::Core
       Array(data.dig("pack", "persist")).map(&:to_s)
     end
 
+    # Host env vars to forward into the container at `space run` (bare passthrough).
+    # Declared per-space so payloads needing credentials run without a wall of flags.
+    def run_env
+      Array(data.dig("run", "env")).map(&:to_s)
+    end
+
     def architect
       data["project"]
     end

data/lib/space_core/templates/oci/dockerfile.erb

@@ -30,18 +30,6 @@ RUN apt-get update -qq \
 # Claude Code CLI (https://claude.ai/install.sh)
 RUN curl -fsSL https://claude.ai/install.sh | bash
 
-# Copy the space tree into the image (filtered by Dockerfile.dockerignore alongside this Dockerfile)
-COPY . /space
-
-# Install space-architect gem: prefer in-space checkout for a pinned version, fall back to RubyGems
-RUN if [ -d /space/repos/space-architect ]; then \
-      cd /space/repos/space-architect \
-   && rake build \
-   && gem install --no-document pkg/*.gem; \
-    else \
-      gem install --no-document space-architect; \
-    fi
-
 # Write entrypoint: sets git safe.directory, execs requested command or a login shell
 RUN echo '<%= entrypoint_b64 %>' | base64 -d > /entrypoint.sh \
  && chmod +x /entrypoint.sh
@@ -52,11 +40,33 @@ RUN printf 'export PATH="/usr/local/bundle/bin:/root/.local/bin:$PATH"\n' \
 <% if provision_scripts.any? -%>
 
 # Space-declared build-time provisioning (pack.provision)
+# Each script is COPY'd individually — a space-content edit elsewhere does not bust its cache layer.
 <% provision_scripts.each do |script| -%>
+COPY <%= script %> /space/<%= script %>
 RUN /space/<%= script %>
 <% end -%>
 <% end -%>
 
+# Install space-architect gem
+<% if local_space_architect? -%>
+COPY repos/space-architect /space/repos/space-architect
+RUN cd /space/repos/space-architect \
+ && rake build \
+ && gem install --no-document pkg/*.gem
+<% else -%>
+RUN gem install --no-document space-architect
+<% end -%>
+
+# Copy the space tree into the image (filtered by Dockerfile.dockerignore alongside this Dockerfile)
+COPY . /space
+<% if persist_paths.any? -%>
+
+# Seed snapshot: capture baked content of persisted dirs so a first-run (empty) mount is seeded from it
+<% persist_paths.each do |guest_path| -%>
+RUN mkdir -p "/opt/space-seed<%= guest_path %>" && cp -a "<%= guest_path %>/." "/opt/space-seed<%= guest_path %>/" 2>/dev/null || true
+<% end -%>
+<% end -%>
+
 WORKDIR /space
 
 ENTRYPOINT ["/entrypoint.sh"]

data/lib/space_core/templates/oci/entrypoint.sh.erb

@@ -3,6 +3,12 @@ set -e
 git config --global --add safe.directory '*'
 git config --global --get user.name >/dev/null 2>&1 || git config --global user.name 'space-architect'
 git config --global --get user.email >/dev/null 2>&1 || git config --global user.email 'architect@localhost'
+<% persist_paths.each do |guest_path| -%>
+if [ -d "/opt/space-seed<%= guest_path %>" ] && [ -z "$(ls -A "<%= guest_path %>" 2>/dev/null)" ]; then
+  mkdir -p "<%= guest_path %>"
+  cp -a "/opt/space-seed<%= guest_path %>/." "<%= guest_path %>/" 2>/dev/null || true
+fi
+<% end -%>
 if [ "$#" -eq 0 ]; then
   exec bash --login
 else

data/lib/space_core/version.rb

@@ -2,6 +2,6 @@
 
 module Space
   module Core
-    VERSION = "2.0.0"
+    VERSION = "2.0.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: space-architect
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.2
 platform: ruby
 authors:
 - Eric Jacobs