space-architect 1.1.0

data/lib/space_architect/space_store.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "async"
+require "async/semaphore"
+require "pathname"
+require "time"
+require "dry/monads"
+require "space_architect/pristine/scm/git"
+require "space_architect/pristine/cloner"
+
+module SpaceArchitect
+  class SpaceStore
+    include Dry::Monads[:result, :maybe]
+
+    MAX_CONCURRENT_CLONES = 5
+
+    attr_reader :config, :state, :now
+
+    def initialize(config:, state:, now: -> { Time.now })
+      @config = config
+      @state = state
+      @now = now
+    end
+
+    def spaces_dir
+      config.spaces_dir
+    end
+
+    def create(title, git: true, git_client: GitClient.new)
+      FileUtils.mkdir_p(spaces_dir)
+      timestamp = now.call
+      id = unique_id("#{timestamp.strftime('%Y%m%d')}-#{Slugger.slug(title)}")
+      path = spaces_dir.join(id)
+
+      FileUtils.mkdir_p(path.join("repos"))
+      FileUtils.mkdir_p(path.join("notes"))
+      FileUtils.mkdir_p(path.join("architecture"))
+      FileUtils.mkdir_p(path.join("tmp"))
+      FileUtils.mkdir_p(path.join("build"))
+      File.write(path.join("build", ".keep"), "")
+
+      space = Space.new(path, metadata_for(id:, title:, timestamp:))
+      space.save
+      write_readme(path:, title:, id:, timestamp:)
+      init_git(path:, id:, git_client:) if git
+      state.touch_recent(id)
+      Success(space)
+    rescue SpaceArchitect::Error => e
+      Failure(e)
+    end
+
+    def list
+      return [] unless spaces_dir.directory?
+
+      spaces_dir.children.select(&:directory?).filter_map do |child|
+        Space.load(child)
+      rescue NotFoundError, Error
+        nil
+      end.sort_by(&:id)
+    end
+
+    def find(identifier = nil, from: Dir.pwd)
+      value = identifier.to_s.strip
+      return current(from:) if value.empty?
+
+      if looks_like_path?(value)
+        begin
+          return Success(Space.load(File.expand_path(value)))
+        rescue SpaceArchitect::Error => e
+          return Failure(e)
+        end
+      end
+
+      matches = matching_spaces(value)
+      return Success(matches.first) if matches.length == 1
+
+      if matches.empty?
+        return Failure(NotFoundError.new("Could not find space matching '#{value}' in #{spaces_dir}"))
+      end
+
+      Failure(AmbiguousSpaceError.new("Space '#{value}' is ambiguous: #{matches.map(&:id).join(', ')}"))
+    rescue SpaceArchitect::Error => e
+      Failure(e)
+    end
+
+    def current(from: Dir.pwd)
+      current_from_pwd(from:).to_result(CurrentSpaceMissingError.new("No current space found from #{from}. Run this inside a space or pass a space id."))
+    rescue SpaceArchitect::Error => e
+      Failure(e)
+    end
+
+    def current_from_pwd(from: Dir.pwd)
+      path = Pathname.new(File.expand_path(from.to_s))
+      path = path.dirname if path.file?
+
+      loop do
+        return Some(Space.load(path)) if path.join(Space::METADATA_FILE).exist?
+        break if path.root?
+
+        path = path.parent
+      end
+
+      None()
+    end
+
+    def path_for(identifier = nil)
+      find(identifier).fmap(&:path)
+    end
+
+    def use(identifier)
+      find(identifier).fmap { |space| state.touch_recent(space.id); space }
+    end
+
+    def add_repo(spec, from: Dir.pwd, scm: Pristine::SCM::Git.new, cloner: nil, mise_client: MiseClient.new)
+      add_repos([spec], from:, scm:, cloner:, mise_client:).fmap(&:first)
+    end
+
+    def add_repos(specs, from: Dir.pwd, scm: Pristine::SCM::Git.new, cloner: nil, mise_client: MiseClient.new, reporter: nil)
+      current(from:).bind { |space| add_repos_to(space, specs, scm:, cloner:, mise_client:, reporter:) }
+    end
+
+    def add_repos_to(space, specs, scm: Pristine::SCM::Git.new, cloner: nil, mise_client: MiseClient.new, reporter: nil)
+      additions = prepare_repo_additions(space, specs)
+      first_error = nil
+
+      Async do |task|
+        semaphore = Async::Semaphore.new(MAX_CONCURRENT_CLONES, parent: task)
+
+        clone_tasks = additions.map do |addition|
+          semaphore.async(finished: false) do
+            clone_addition(addition, scm:, cloner:, mise_client:, reporter:)
+          end
+        end
+
+        # Collect results without raising inside the reactor so the outer task
+        # succeeds and async does not log "Task may have ended" for our errors.
+        clone_tasks.each do |ct|
+          ct.wait
+        rescue StandardError => e
+          first_error ||= e
+        end
+      end.wait
+
+      return Failure(first_error) if first_error
+
+      Success(additions.map do |addition|
+        repo_data = space.add_repo(addition.fetch(:reference), relative_path: addition.fetch(:relative_path), now: now.call)
+        { space: space, repo: repo_data, reference: addition.fetch(:reference), path: addition.fetch(:path) }
+      end)
+    rescue SpaceArchitect::Error => e
+      Failure(e)
+    end
+
+    def repos(from: Dir.pwd)
+      current(from:).fmap(&:repos)
+    end
+
+    private
+
+    def clone_addition(addition, scm:, cloner:, mise_client:, reporter: nil)
+      reporter&.start(addition)
+      fetch_addition(addition, scm:, cloner:)
+      reporter&.trust(addition)
+      mise_client.trust(addition.fetch(:path))
+      reporter&.finish(addition)
+      addition
+    rescue StandardError
+      reporter&.fail(addition)
+      raise
+    end
+
+    # Prefer a fast local src copy; fall back to a network clone only when no
+    # src copy is available.
+    def fetch_addition(addition, scm:, cloner:)
+      reference = addition.fetch(:reference)
+      destination = addition.fetch(:path)
+      source = addition.fetch(:src_source)
+
+      if source&.directory?
+        actual_cloner = cloner || Pristine::Cloner.new(base_dir: config.src_dir)
+        result = actual_cloner.call(name: reference.full_name, into: destination.dirname.to_s)
+        raise GitError, "clone failed (copy): #{result.failure}" if result.failure?
+      else
+        result = scm.clone(reference.clone_url, destination.to_s)
+        raise GitError, "clone failed: #{result.failure[:stderr]}" if result.failure?
+      end
+    end
+
+    def prepare_repo_additions(space, specs)
+      src_dir = config.src_dir
+      additions = specs.map do |spec|
+        reference = RepoResolver.new(config).resolve(spec)
+        relative_path = Pathname.new("repos").join(reference.directory_name)
+        destination = space.path.join(relative_path)
+
+        ensure_repo_can_be_added!(space, reference, relative_path, destination)
+
+        {
+          reference: reference,
+          relative_path: relative_path,
+          path: destination,
+          src_source: src_dir && reference.src_path(src_dir)
+        }
+      end
+
+      duplicate_paths = additions
+        .map { |addition| addition.fetch(:path).to_s }
+        .tally
+        .select { |_path, count| count > 1 }
+        .keys
+      unless duplicate_paths.empty?
+        raise RepoExistsError, "Multiple repos resolve to the same destination: #{duplicate_paths.join(', ')}"
+      end
+
+      additions
+    end
+
+    def ensure_repo_can_be_added!(space, reference, relative_path, destination)
+      raise RepoExistsError, "Repo destination already exists: #{destination}" if destination.exist?
+
+      existing = space.repos.find do |repo|
+        repo["full_name"] == reference.full_name ||
+          repo["path"] == relative_path.to_s ||
+          repo["name"] == reference.name
+      end
+      return unless existing
+
+      raise RepoExistsError, "Repo '#{reference.full_name}' already exists in #{space.id}"
+    end
+
+    def metadata_for(id:, title:, timestamp:)
+      iso_timestamp = timestamp.iso8601
+      {
+        "version" => 1,
+        "id" => id,
+        "title" => title,
+        "status" => "active",
+        "created_at" => iso_timestamp,
+        "updated_at" => iso_timestamp,
+        "repos" => [],
+        "notes" => [],
+        "tickets" => [],
+        "tags" => []
+      }
+    end
+
+    def write_readme(path:, title:, id:, timestamp:)
+      AtomicWrite.write(path.join("README.md"), <<~README)
+        # #{title}
+
+        Space: `#{id}`
+        Created: #{timestamp.iso8601}
+
+        ## Organization
+
+        - `space.yaml` tracks the space identity, status, and associated metadata.
+        - `repos/` contains cloned Git repositories for this work.
+        - `notes/` is for task notes, scratch docs, and thinking-in-progress.
+        - `architecture/` holds the architect mission memory (ARCHITECT.md and the per-iteration files).
+        - `tmp/` is the workspace-local scratch directory. Use it instead of `/tmp` or
+          `/var/tmp`; when using `mktemp`, use `tmp/` as the base directory.
+        - `build/` holds the architect loop's per-lane worktrees and scratch
+          (gitignored except `.keep`).
+        - The space is a Git repository so notes and architecture are versioned.
+          `repos/`, `tmp/`, and `build/` are gitignored, keeping the cloned repos and scratch
+          out of the space's history (each clone keeps its own Git repo).
+      README
+    end
+
+    # Make the space itself a Git repo so its notes/architecture are versioned.
+    # `repos/` and `tmp/` are ignored: the clones keep their own `.git`, and a
+    # space-level `git add` must never pull them in as embedded-repo gitlinks.
+    def init_git(path:, id:, git_client:)
+      write_gitignore(path)
+      git_client.init(path)
+      git_client.commit_all(path, "Initialize space #{id}")
+    end
+
+    def write_gitignore(path)
+      AtomicWrite.write(path.join(".gitignore"), <<~GITIGNORE)
+        repos/
+        tmp/
+        build/
+        !build/.keep
+      GITIGNORE
+    end
+
+    def unique_id(base_id)
+      candidate = base_id
+      counter = 2
+
+      while spaces_dir.join(candidate).exist?
+        candidate = "#{base_id}-#{counter}"
+        counter += 1
+      end
+
+      candidate
+    end
+
+    def looks_like_path?(value)
+      value.include?(File::SEPARATOR) || value.start_with?("~") || value.start_with?(".")
+    end
+
+    def matching_spaces(value)
+      all = list
+      exact = all.select { |space| space.id == value }
+      return exact unless exact.empty?
+
+      suffix = all.select { |space| space.id.end_with?("-#{value}") }
+      return suffix unless suffix.empty?
+
+      prefix = all.select { |space| space.id.start_with?(value) }
+      return prefix unless prefix.empty?
+
+      all.select { |space| space.id.include?(value) }
+    end
+  end
+end

data/lib/space_architect/state.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+
+module SpaceArchitect
+  class State
+    DEFAULT_DATA = {
+      "version" => 1,
+      "current_space" => nil,
+      "recent" => []
+    }.freeze
+
+    attr_reader :path, :data, :env
+
+    def self.default_path(env: ENV)
+      XDG.state_home(env: env).join("space-architect", "state.yml")
+    end
+
+    def self.load(env: ENV, path: default_path(env: env))
+      new(env:, path:).load
+    end
+
+    def initialize(env: ENV, path: self.class.default_path(env: env), data: nil)
+      @path = Pathname.new(path)
+      @env = env
+      @data = data ? default_data.merge(stringify_keys(data)) : default_data
+    end
+
+    def load
+      @data = if path.exist?
+                parsed = YAML.safe_load(path.read, aliases: false) || {}
+                unless parsed.is_a?(Hash)
+                  raise Error, "State file must contain a YAML mapping: #{path}"
+                end
+
+                default_data.merge(stringify_keys(parsed))
+              else
+                default_data
+              end
+      self
+    end
+
+    def ensure_exists!
+      save unless path.exist?
+      self
+    end
+
+    def save
+      AtomicWrite.write(path, YAML.dump(data))
+      self
+    end
+
+    def current_space
+      data["current_space"]
+    end
+
+    def current_space=(space_id)
+      data["current_space"] = space_id
+    end
+
+    def recent
+      Array(data["recent"])
+    end
+
+    def touch_current(space_id)
+      self.current_space = space_id
+      touch_recent(space_id)
+    end
+
+    def touch_recent(space_id)
+      data["recent"] = ([space_id] + recent).compact.uniq.first(20)
+      save
+    end
+
+    private
+
+    def default_data
+      DEFAULT_DATA.merge("recent" => [])
+    end
+
+    def stringify_keys(hash)
+      hash.each_with_object({}) { |(key, value), result| result[key.to_s] = value }
+    end
+  end
+end

data/lib/space_architect/templates/architect.md.erb

@@ -0,0 +1,48 @@
+# ARCHITECT — <%= @_title %>
+
+> Cross-iteration table of contents for the Architect Loop. Per-iteration detail lives in
+> architecture/I<NN>-<iteration>.md — this file only indexes the iterations and carries
+> mission-wide state. Keep it short (~150 lines): the next session must grok it
+> in under a minute. Not in the committed architecture = didn't happen.
+
+## TL;DR (keep current)
+
+- Goal: _[one sentence]_
+- Last iteration: _[I<NN>-name — CONTINUE / KILL / awaiting verdict]_
+- Next action: _[exact command or decision needed]_
+
+## Repos in scope
+
+| Repo | Path |
+|------|------|
+<% @_repos.each do |repo| -%>
+| <%= repo["full_name"] || repo["name"] %> | <%= repo["path"] || "" %> |
+<% end -%>
+<% if @_repos.empty? -%>
+| _(none yet — add repos with `space repo add`)_ | |
+<% end -%>
+
+## Verification gate (exact commands, per repo)
+
+```
+[install / test / lint / typecheck / build commands for each repo in scope]
+```
+
+## Iteration index
+
+<!-- Add a row per iteration. Create iterations with `architect new <name>`. -->
+
+| I# | Iteration | Status | freeze_sha | Integration branch | Verdict | File |
+|----|-----------|--------|-----------|--------------------|---------|------|
+
+Status values: speccing → frozen → dispatched → in-flight → awaiting-verdict → done.
+
+## Open items for the human / architect
+
+<!-- Blocking items: unresolved disagreements (which iteration), scope questions,
+stop-condition checkpoints. Detail lives in the iteration file; link it. -->
+
+## Decisions log (architect + human)
+
+| Date | Decision | Why |
+|------|----------|-----|

data/lib/space_architect/templates/iteration.md.erb

@@ -0,0 +1,66 @@
+# <%= @_ordinal %>: <%= @_name %>
+
+> One self-contained iteration of the Architect Loop. Grown section by section, one
+> commit per section. The builder NEVER edits this file — the architect writes
+> every section, and transcribes the Builder Report verbatim from the builder's
+> scratch report in build/. Frozen sections (Grounds, Specification, Acceptance Criteria)
+> are read-only after the freeze commit; only Builder Prompt, Builder Report, and
+> Verdict are appended afterward.
+
+## Grounds
+
+<!-- WHY. Research/PRD distilled: problem, decision + why, requirements,
+non-goals, verified facts WITH citation URLs, open questions. Optional — delete
+this section for iterations that needed no research. Commit: "<%= @_ordinal %>: grounds". -->
+
+## Specification
+
+<!-- WHAT / HOW — the full, self-contained delegation contract.
+Commit: "<%= @_ordinal %>: specification". -->
+
+- **Objective** — what to build and why (cite Grounds if present).
+- **Output format** — raw tables, numbers, commit SHAs, test output paths.
+- **Tool guidance** — exact verification commands for the target repo; the
+  APIs/formats/versions to verify against live dependencies before writing code.
+- **Boundaries** — may-touch / must-not-touch / out-of-scope; no placeholders;
+  no refactors beyond the task.
+- **Lane plan** — 1–4 lanes, each declaring: target repo `repos/<repo>`,
+  file-touch set (overlap-checked), objective, output format, boundaries.
+- **Effort** — `think hard` … `ultrathink` per lane, with one line of why.
+
+## Acceptance Criteria
+
+<!-- PROOF. Exact gate commands + thresholds. `architect freeze <%= @_name %>`
+commits this file and records its SHA as freeze_sha. Read-only afterward — any
+change to Grounds/Specification/Acceptance Criteria = automatic iteration FAIL. -->
+
+| AC# | Command | Threshold |
+|-----|---------|-----------|
+|     |         |           |
+
+## Builder Prompt
+
+<!-- The exact lane-prompt(s) dispatched, recorded as provenance. One ###
+subsection per lane. A copy is written to build/<%= @_ordinal %>-<%= @_name %>-<lane>/prompt.md
+for stdin dispatch. Commit: "<%= @_ordinal %>: dispatched". -->
+
+## Builder Report
+
+<!-- RAW EVIDENCE ONLY — tables, numbers, command output. The builder writes this
+to build/<%= @_ordinal %>-<%= @_name %>-<lane>/report.md; the architect transcribes it here
+VERBATIM (no interpretation). One ### subsection per lane; include the builder's
+PHASE 0 disagreements and its STATUS line. Commit: "<%= @_ordinal %>: evidence". -->
+
+## Verdict
+
+<!-- ARCHITECT JUDGMENT, written in a LATER session than the dispatch.
+Commit: "<%= @_ordinal %>: verdict". -->
+
+- **Disagreement rulings** — each PHASE 0 disagreement: ACCEPT / REJECT / MODIFY + why.
+- **Acceptance Criteria integrity** — frozen sections unchanged since freeze (`architect verify <%= @_name %>`)?
+
+| AC# | Raw result | Verdict |
+|-----|------------|---------|
+|     |            | PASS/FAIL/INVALID |
+
+- **Iteration** — KILL / CONTINUE + the single decisive reason.

data/lib/space_architect/terminal.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "async"
+require "pastel"
+
+module SpaceArchitect
+  class Terminal
+    SPINNER_FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+
+    attr_reader :stdout, :stderr, :config
+
+    def initialize(config:, stdout: $stdout, stderr: $stderr, color_mode: "auto")
+      @config = config
+      @stdout = stdout
+      @stderr = stderr
+      @color_mode = color_mode.to_s.downcase
+      color_mode
+    end
+
+    def interactive?
+      stderr.tty?
+    end
+
+    def pastel
+      @pastel ||= Pastel.new(enabled: colors_enabled?)
+    end
+
+    def say(message = "")
+      stdout.puts(message)
+    end
+
+    def error(message)
+      stderr.puts(colors_enabled? ? pastel.red(message) : message)
+    end
+
+    def success(message)
+      say pastel.green(message)
+    end
+
+    def table(headers, rows)
+      column_widths = headers.each_index.map do |index|
+        ([headers[index]] + rows.map { |row| row[index].to_s }).map(&:length).max
+      end
+
+      ([headers] + rows).each_with_index.map do |row, row_index|
+        table_row(headers, row, column_widths, header: row_index.zero?)
+      end.join("\n")
+    end
+
+    def path(path)
+      value = path.to_s
+      homes.each do |home|
+        return "~" if value == home
+        return "~#{value.delete_prefix(home)}" if value.start_with?("#{home}/")
+      end
+
+      value
+    end
+
+    def with_spinner(message)
+      return yield unless interactive?
+
+      Async do |task|
+        spinner_task = start_spinner(task, message)
+        yield
+      ensure
+        spinner_task&.stop
+        begin
+          spinner_task&.wait
+        rescue StandardError
+          nil
+        end
+        clear_spinner
+      end.wait
+    end
+
+    private
+
+    def color_mode
+      return @color_mode if %w[auto always never].include?(@color_mode)
+
+      raise Error, "Invalid color mode '#{@color_mode}'. Expected one of: auto, always, never"
+    end
+
+    def colors_enabled?
+      case color_mode
+      when "always"
+        true
+      when "never"
+        false
+      else
+        stdout.tty?
+      end
+    end
+
+    def homes
+      home = XDG.home(env: config.env)
+      [home, realpath_or_nil(home)].compact.uniq
+    end
+
+    def realpath_or_nil(path)
+      File.realpath(path)
+    rescue SystemCallError
+      nil
+    end
+
+    def table_row(headers, row, column_widths, header: false)
+      row.each_with_index.map do |cell, index|
+        raw = cell.to_s
+        styled = header ? pastel.bold(raw) : style_table_cell(headers[index], raw)
+        "#{styled}#{' ' * (column_widths[index] - raw.length)}"
+      end.join("   ").rstrip
+    end
+
+    def style_table_cell(header, value)
+      case header
+      when "Status"
+        style_status(value)
+      when "Date"
+        pastel.dim(value)
+      when "Path"
+        pastel.cyan(value)
+      else
+        value
+      end
+    end
+
+    def style_status(status)
+      case status
+      when "active"
+        pastel.green(status)
+      when "paused"
+        pastel.yellow(status)
+      when "done"
+        pastel.blue(status)
+      when "archived"
+        pastel.bright_black(status)
+      else
+        status
+      end
+    end
+
+    def start_spinner(task, message)
+      task.async do |spinner|
+        frame_index = 0
+
+        loop do
+          text = message.respond_to?(:call) ? message.call : message.to_s
+          frame = SPINNER_FRAMES[frame_index % SPINNER_FRAMES.length]
+          stderr.print "\r\e[2K#{pastel.cyan(frame)} #{text}"
+          stderr.flush
+          frame_index += 1
+          spinner.sleep(0.1)
+        end
+      end
+    end
+
+    def clear_spinner
+      stderr.print "\r\e[2K"
+      stderr.flush
+    end
+  end
+end

data/lib/space_architect/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SpaceArchitect
+  VERSION = "1.1.0"
+end

data/lib/space_architect/warnings.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SpaceArchitect
+  module Warnings
+    module_function
+
+    def disable_experimental!
+      return unless Warning.respond_to?(:[]) && Warning.respond_to?(:[]=)
+
+      Warning[:experimental] = false
+    end
+  end
+end