ace-design 0.2.0

data/lib/ace/design/organisms/generator.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+require "fileutils"
+require "digest"
+require "ace/bundle"
+require "time"
+module Ace
+  module Design
+    module Organisms
+      class Generator
+        def initialize(config: Design.config, executor: Molecules::AgentExecutor.new)
+          @config, @executor = config, executor
+        end
+        def generate(surface: nil, prompt: nil, prompt_append: [], intent: "explore", from: nil, preset: "fast", input: [], fixtures: nil, model: nil,
+          variant_prompts: [], variant_prompt_files: [], language: nil, dry_run: false, kind: nil, profile: nil)
+          raise Error, "Unknown intent: #{intent}" unless %w[explore recreate reimagine].include?(intent)
+          raise Error, "explore does not accept --from" if intent == "explore" && from
+          raise Error, "#{intent} requires --from" if intent != "explore" && !from
+          source = Molecules::DesignSource.new(from, config: @config)
+          surface, kind = Molecules::DesignSource.scope(surface: surface, kind: kind, profile: profile, source: source.info)
+          origin = prompt.nil? ? "default" : "explicit"
+          if prompt.nil? && source.info&.fetch("type") == "session"
+            prompt = File.read(File.join(source.info.fetch("root"), "brief.md"))
+            origin = "session"
+          end
+          prompt ||= "#{intent.capitalize} the supplied interface, preserving its goals and functions." unless intent == "explore"
+          Atoms::Contracts.text(prompt, "prompt")
+          raise Error, "prompt_append must be a list" unless prompt_append.is_a?(Array)
+          prompt_append.each { |text| Atoms::Contracts.text(text, "prompt-append") }
+          brief_inputs = {"origin" => origin, "base" => prompt, "append" => prompt_append.dup}
+          prompt = ([prompt] + prompt_append).join("\n\n")
+          assumptions = Molecules::DesignContext.new.snapshot(surface: surface, kind: kind, context: profile, readonly: dry_run)
+          language ||= @config.fetch("language")
+          Atoms::Contracts.text(language, "language")
+          resolved = Molecules::Preset.load(name: preset, surface: surface, config: @config, model: model,
+            prompts: variant_prompts, prompt_files: variant_prompt_files, kind: kind, intent: intent)
+          # Validate all declarations before creating a session or starting preparation.
+          @executor.validate_model(resolved.fetch("preparation_model"))
+          resolved.fetch("variants").each do |slot|
+            @executor.validate_model(slot.fetch("model"), execution_preset: slot["execution_preset"])
+          end
+          begin
+            fixture_bytes = fixtures && File.binread(fixtures)
+          rescue SystemCallError => e
+            raise Error, "Cannot read --fixtures #{fixtures}: #{e.message}"
+          end
+          Atoms::Contracts.object(JSON.parse(fixture_bytes), "fixtures") if fixture_bytes
+          snapshot = load_context(resolved.fetch("input") + input)
+          requirements = Molecules::SkillSources.new(@config).requirements(resolved) + source.requirements
+          resolved["brief_inputs"] = brief_inputs
+          resolved["requirements"] = requirements
+          resolved["profile"] = assumptions.reject { |key, _| key == "document" }
+          resolved["source"] = source.info
+          resolved["surface"], resolved["kind"] = surface, kind
+          if dry_run
+            return {"status" => "planned", "resolved" => resolved, "requirements" => requirements, "brief" => prompt, "input_snapshot" => snapshot,
+              "fixtures_sha256" => fixture_bytes && Digest::SHA256.hexdigest(fixture_bytes),
+              "next" => "Run the same command without --dry-run"}
+          end
+          missing = requirements.select { |entry| entry["status"] == "missing" }
+          raise Error, "Missing preset requirements: #{missing.map { |r| r['name'] }.join(', ')}" unless missing.empty?
+          root = allocate_session
+          source.snapshot(root)
+          Molecules::SkillSources.new(@config).snapshot(root, resolved)
+          metadata = {"intent" => intent, "source" => source.info, "surface" => surface, "kind" => kind, "title" => prompt.lines.find { |line| !line.strip.empty? }.strip[0, 120], "language" => language,
+            "variants" => resolved.fetch("variants").map { |s| s.fetch("id") }}
+          Molecules::Artifacts.json(File.join(root, "session.json"), metadata)
+          Molecules::Artifacts.json(File.join(root, "resolved.json"), resolved)
+          File.write(File.join(root, "brief.md"), prompt)
+          File.write(File.join(root, "context.md"), snapshot)
+          File.write(File.join(root, "design.md"), assumptions.fetch("document"))
+          File.binwrite(File.join(root, "fixtures.json"), fixture_bytes) if fixture_bytes
+          state = {"project_root" => Dir.pwd, "status" => "prepared", "preparation" => {"status" => "pending"},
+            "supplied_fixtures" => !!fixture_bytes,
+            "inputs" => %w[brief.md context.md design.md session.json resolved.json].to_h { |f| [f, Digest::SHA256.file(File.join(root, f)).hexdigest] },
+            "workers" => metadata.fetch("variants").to_h { |id| [id, {"status" => "pending", "attempts" => []}] }}
+          state["inputs"]["fixtures.json"] = Digest::SHA256.hexdigest(fixture_bytes) if fixture_bytes
+          %w[source skills].each do |folder|
+            directory = File.join(root, folder)
+            next unless File.directory?(directory)
+            Molecules::Artifacts.files(directory).each do |file|
+              state["inputs"]["#{folder}/#{file}"] = Digest::SHA256.file(File.join(directory, file)).hexdigest
+            end
+          end
+          Molecules::Artifacts.json(File.join(root, "run.json"), state)
+          FileUtils.mkdir_p(File.join(root, "prompts"))
+          File.write(File.join(root, "prompts/system.md"), Molecules::DesignPrompts::SYSTEM)
+          File.write(File.join(root, "prompts/preparation.md"), Molecules::DesignPrompts.preparation(metadata, resolved, supplied: !!fixture_bytes))
+          resolved.fetch("variants").each do |slot|
+            File.write(File.join(root, "prompts/#{slot.fetch('id')}.md"), Molecules::DesignPrompts.variant(metadata, slot))
+          end
+          warn "Design session: #{root}"
+          run = DesignRun.new(root, executor: @executor)
+          run.resume
+        rescue JSON::ParserError => e
+          raise Error, "Invalid fixtures JSON: #{e.message}"
+        ensure
+          FileUtils.rm_rf(root) if root && !File.file?(File.join(root, "run.json"))
+        end
+        private
+        def allocate_session
+          base = File.expand_path(@config.fetch("run_root"))
+          FileUtils.mkdir_p(base)
+          100.times do
+            root = File.join(base, Ace::B36ts.encode(Time.now, format: :ms))
+            begin
+              Dir.mkdir(root)
+              return root
+            rescue Errno::EEXIST
+              sleep 0.002
+            end
+          end
+          raise Error, "Could not allocate a unique Base36 session"
+        end
+        def load_context(inputs)
+          inputs.map do |input|
+            Atoms::Contracts.text(input, "context reference")
+            bundle = Ace::Bundle.load_auto(input, compressor: "off", allow_commands: false, allowed_root: Dir.pwd)
+            error = bundle.metadata[:error] || bundle.metadata["error"]
+            raise Error, "Context #{input}: #{error}" if error
+            raise Error, "Context #{input} is empty" if bundle.content.to_s.strip.empty?
+            "# Context: #{input}\n\n#{bundle.content}"
+          end.join("\n\n")
+        end
+      end
+    end
+  end
+end

data/lib/ace/design/organisms/inspector.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+require "fileutils"
+require "securerandom"
+module Ace
+  module Design
+    module Organisms
+      class Inspector
+        def initialize(config: Design.config, runtime: nil)
+          @config = config
+          @runtime = runtime || Molecules::Runtime.new(config)
+        end
+        def run(url:, surface:, out: nil)
+          Atoms::Contracts.url(url)
+          Atoms::Contracts.surface(surface)
+          seconds = Integer(@config.fetch("timeout"))
+          raise Error, "timeout must be between 1 and 300 seconds" unless (1..300).cover?(seconds)
+          output = File.expand_path(out || File.join(@config.fetch("run_root"), "#{Ace::B36ts.now}-#{SecureRandom.hex(4)}", "inspection"))
+          if File.symlink?(output) || (File.exist?(output) && (!File.directory?(output) || !Dir.empty?(output)))
+            raise Error, "Inspection output must be new or empty: #{output}"
+          end
+          FileUtils.mkdir_p(output)
+          owned_output = true
+          result = @runtime.capture(@runtime.node, @runtime.script("inspect.mjs"), url, surface, output,
+            @runtime.directory, seconds.to_s, timeout: seconds * 3 + 30)
+          report_path = File.join(output, "report.json")
+          raise Error, "Runner produced no report: #{result['stderr']}" unless File.file?(report_path)
+          report = JSON.parse(File.read(report_path))
+          unless report.is_a?(Hash) && %w[pass findings incomplete].include?(report["status"]) && report["viewports"].is_a?(Array)
+            raise Error, "Runner produced an invalid inspection report"
+          end
+          if report["status"] == "pass" && (report["viewports"].map { |v| v["width"] }.sort != [390, 768, 1440] ||
+              !report.fetch("errors", ["missing errors"]).empty? || !report.fetch("findings", ["missing findings"]).empty?)
+            raise Error, "Runner pass report lacks complete clean evidence"
+          end
+          if result["exit_code"] != 0 && report["status"] == "pass"
+            raise Error, "Runner failed despite a pass report: #{result['stderr']}"
+          end
+          report.merge("report_path" => report_path)
+        rescue JSON::ParserError => e
+          raise Error, "Invalid inspection JSON: #{e.message}"
+        rescue Error => e
+          if defined?(owned_output) && owned_output && File.directory?(output) && !File.exist?(File.join(output, "report.json"))
+            File.write(File.join(output, "error.json"), JSON.pretty_generate({"status" => "incomplete", "error" => e.message}))
+          end
+          raise
+        end
+      end
+    end
+  end
+end

data/lib/ace/design/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+module Ace
+  module Design
+    VERSION = "0.2.0"
+  end
+end

data/lib/ace/design.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+require "json"
+require "yaml"
+require "date"
+require "ace/support/config"
+require "ace/support/cli"
+require "ace/b36ts"
+require_relative "design/version"
+module Ace
+  module Design
+    class Error < StandardError; end
+    def self.gem_root
+      File.expand_path("../..", __dir__)
+    end
+    def self.config
+      defaults = YAML.safe_load_file(File.join(gem_root, ".ace-defaults/design/config.yml"))
+      overrides = Ace::Support::Config.create(gem_path: gem_root).resolve_namespace("design").to_h
+      Ace::Support::Config::Models::Config.wrap(defaults, overrides).fetch("design")
+    end
+  end
+end
+require_relative "design/atoms/contracts"
+require_relative "design/molecules/preset"
+require_relative "design/molecules/artifacts"
+require_relative "design/molecules/agent_executor"
+require_relative "design/molecules/context_document"
+require_relative "design/molecules/context_repository"
+require_relative "design/molecules/design_context"
+require_relative "design/molecules/adjust_prompts"
+require_relative "design/organisms/adjuster"
+require_relative "design/molecules/design_source"
+require_relative "design/molecules/skill_sources"
+require_relative "design/molecules/design_prompts"
+require_relative "design/molecules/session"
+require_relative "design/organisms/design_run"
+require_relative "design/organisms/generator"
+require_relative "design/molecules/catalog"
+require_relative "design/molecules/runtime"
+require_relative "design/organisms/inspector"
+require_relative "design/cli"

metadata

@@ -0,0 +1,280 @@
+--- !ruby/object:Gem::Specification
+name: ace-design
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Michal Czyz
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ace-support-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: ace-support-config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: ace-llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.42'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.42'
+- !ruby/object:Gem::Dependency
+  name: ace-llm-providers-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.36.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.36.2
+- !ruby/object:Gem::Dependency
+  name: ace-bundle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.45'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.45'
+- !ruby/object:Gem::Dependency
+  name: ace-b36ts
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: ace-support-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.32'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.32'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.19'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Shared site/app design workflows, local mockup previews, browser inspection
+  and curated inspiration.
+email:
+- mc@cs3b.com
+executables:
+- ace-design
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ace-defaults/design/config.yml"
+- ".ace-defaults/design/contexts/app.md"
+- ".ace-defaults/design/contexts/app/component.md"
+- ".ace-defaults/design/contexts/app/view.md"
+- ".ace-defaults/design/contexts/project.md"
+- ".ace-defaults/design/contexts/site.md"
+- ".ace-defaults/design/contexts/site/component.md"
+- ".ace-defaults/design/contexts/site/view.md"
+- ".ace-defaults/design/presets/ace-vs-taste.yml"
+- ".ace-defaults/design/presets/fast.yml"
+- ".ace-defaults/design/presets/impeccable.yml"
+- ".ace-defaults/design/presets/superdesign.yml"
+- ".ace-defaults/design/presets/taste-v2.yml"
+- ".ace-defaults/design/presets/ui-ux-pro-max.yml"
+- ".ace-defaults/nav/protocols/guide-sources/ace-design.yml"
+- ".ace-defaults/nav/protocols/skill-sources/ace-design.yml"
+- ".ace-defaults/nav/protocols/tmpl-sources/ace-design.yml"
+- ".ace-defaults/nav/protocols/wfi-sources/ace-design.yml"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- browser/dependencies.mjs
+- browser/doctor.mjs
+- browser/inspect.mjs
+- browser/package-lock.json
+- browser/package.json
+- browser/preview.mjs
+- browser/source.mjs
+- docs/contexts.md
+- docs/inspiration.md
+- docs/intent-verification.md
+- docs/runner.md
+- docs/testing.md
+- docs/usage.md
+- exe/ace-design
+- handbook/benchmarks/app-booking/brief.md
+- handbook/benchmarks/app-booking/fixtures.json
+- handbook/benchmarks/app-inventory/brief.md
+- handbook/benchmarks/app-inventory/fixtures.json
+- handbook/benchmarks/app-support/brief.md
+- handbook/benchmarks/app-support/fixtures.json
+- handbook/benchmarks/site-community/brief.md
+- handbook/benchmarks/site-community/fixtures.json
+- handbook/benchmarks/site-course/brief.md
+- handbook/benchmarks/site-course/fixtures.json
+- handbook/benchmarks/site-studio/brief.md
+- handbook/benchmarks/site-studio/fixtures.json
+- handbook/catalog/app/error-recovery.md
+- handbook/catalog/app/status-feedback.md
+- handbook/catalog/app/task-first-density.md
+- handbook/catalog/shared/automated-a11y-boundary.md
+- handbook/catalog/shared/bounded-exploration.md
+- handbook/catalog/shared/context-before-style.md
+- handbook/catalog/shared/contextual-cards.md
+- handbook/catalog/shared/focus-visible.md
+- handbook/catalog/shared/responsive-reflow.md
+- handbook/catalog/site/critique-versus-defect.md
+- handbook/catalog/site/purposeful-links.md
+- handbook/catalog/site/subject-specific-hero.md
+- handbook/guides/design/process.g.md
+- handbook/skills/as-design-app-adjust/SKILL.md
+- handbook/skills/as-design-app-audit/SKILL.md
+- handbook/skills/as-design-app-implement/SKILL.md
+- handbook/skills/as-design-app/SKILL.md
+- handbook/skills/as-design-look-for-inspiration/SKILL.md
+- handbook/skills/as-design-site-adjust/SKILL.md
+- handbook/skills/as-design-site-audit/SKILL.md
+- handbook/skills/as-design-site-implement/SKILL.md
+- handbook/skills/as-design-site/SKILL.md
+- handbook/templates/design/benchmark-result.template.md
+- handbook/templates/design/brief.template.md
+- handbook/templates/design/feedback.template.md
+- handbook/templates/design/proposal.template.md
+- handbook/templates/design/source-ledger.template.md
+- handbook/workflow-instructions/design/adjust.wf.md
+- handbook/workflow-instructions/design/audit.wf.md
+- handbook/workflow-instructions/design/explore.wf.md
+- handbook/workflow-instructions/design/implement.wf.md
+- handbook/workflow-instructions/design/look-for-inspiration.wf.md
+- lib/ace/design.rb
+- lib/ace/design/atoms/contracts.rb
+- lib/ace/design/cli.rb
+- lib/ace/design/cli/commands/adjust.rb
+- lib/ace/design/cli/commands/doctor.rb
+- lib/ace/design/cli/commands/explore.rb
+- lib/ace/design/cli/commands/inspect.rb
+- lib/ace/design/cli/commands/preset.rb
+- lib/ace/design/cli/commands/preview.rb
+- lib/ace/design/cli/commands/run_commands.rb
+- lib/ace/design/cli/commands/validate.rb
+- lib/ace/design/molecules/adjust_prompts.rb
+- lib/ace/design/molecules/agent_executor.rb
+- lib/ace/design/molecules/artifacts.rb
+- lib/ace/design/molecules/catalog.rb
+- lib/ace/design/molecules/context_document.rb
+- lib/ace/design/molecules/context_repository.rb
+- lib/ace/design/molecules/design_context.rb
+- lib/ace/design/molecules/design_prompts.rb
+- lib/ace/design/molecules/design_source.rb
+- lib/ace/design/molecules/preset.rb
+- lib/ace/design/molecules/runtime.rb
+- lib/ace/design/molecules/session.rb
+- lib/ace/design/molecules/skill_sources.rb
+- lib/ace/design/organisms/adjuster.rb
+- lib/ace/design/organisms/design_run.rb
+- lib/ace/design/organisms/generator.rb
+- lib/ace/design/organisms/inspector.rb
+- lib/ace/design/version.rb
+homepage: https://github.com/cs3b/ace
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/cs3b/ace/tree/main/ace-design
+  changelog_uri: https://github.com/cs3b/ace/blob/main/ace-design/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Fast interactive web design directions, production handoff and browser evidence
+test_files: []