مواد پر جائیں

ماحول سیٹ اپ کریں

ماحول ایک اسپیس کا چلتا ہوا اسٹیک ہے: وہ سروسز جو کسی برانچ کو درکار ہیں، باقی تمام اسپیسز سے الگ، سائیڈ بار میں نظر آتی ہیں اور ایجنٹس کی پہنچ میں ہیں۔ پل ریکویسٹس کو بھی ایک ملتا ہے، کیونکہ PR کی اپنی اسپیس پہلے سے ہوتی ہے۔

ورک اسپیس ایڈمن ایک بار تعریف لکھتا ہے۔ پھر ممبرز اسپیس یا PR کی سائیڈ بار کے ماحول حصے میں شروع دباتے ہیں۔ تعریفیں ورک اسپیس کے ڈیٹا بیس میں رہتی ہیں، اس لیے فیچر برانچ کبھی نہیں بدلتی کہ Control Center کیا چلاتا ہے، اگرچہ ٹولز پھر بھی اس برانچ کا کوڈ چلاتے ہیں۔

  1. ترتیبات → ورک اسپیس → ماحول کھولیں۔ صرف ورک اسپیس ایڈمن تعریفیں بدل سکتے ہیں، اور صرف سرور کا مالک وہ تعریف محفوظ کر سکتا ہے جو سرور ہوسٹ پر چلتی ہو (دیکھیں کون کیا محفوظ کر سکتا ہے)۔
  2. نئی تعریف پر کلک کریں، پھر خالی تعریف یا ریپو سے مسودہ پر۔ ڈرافٹ ریپو میں compose فائلیں، Procfile اور package.json اسکرپٹس تلاش کرتا ہے، اور نتیجے کا جائزہ آپ لیتے ہیں۔
  3. فارم بھریں، یا JSON ٹیب استعمال کریں۔ اس صفحے کی مثالیں وہی JSON ہیں۔
  4. ٹیسٹ چلائیں پر کلک کریں۔ یہ ایک عارضی ماحول شروع کرتا ہے، تیار ہونے تک انتظار کرتا ہے اور اسے ختم کر دیتا ہے۔

محفوظ کرتے وقت تعریف کی سختی سے جانچ ہوتی ہے۔ نامعلوم فیلڈ، غلط قسم کی قدر یا غلط ہجے والا انتخاب مسترد ہو جاتا ہے، ساتھ اس کا راستہ اور قریب ترین درست نام، جیسے repos.app.requird: Unknown field. Did you mean "required"?۔ اوپری سطح پر $schema کی اجازت ہے۔

تعریف کو ریپو میں رکھنے کے لیے ریپو فائل لنک کریں استعمال کریں۔ Control Center فائل صرف ڈیفالٹ برانچ سے پڑھتا ہے اور صرف وہی ورژن چلاتا ہے جو منظور ہوا ہو: ورک اسپیس ایڈمن کی منظوری سے، یا جب تعریف ہوسٹ پر چلتی ہو تو سرور کے مالک کی منظوری سے۔ نیا ورژن اپ ڈیٹ دستیاب ہے دکھاتا ہے اور منظوری تک کچھ نہیں بدلتا۔

ماحول کی تعریف سرور ہوسٹ پر سرور کے اپنے صارف کے طور پر کمانڈز چلا سکتی ہے۔ یہ فیصلہ سرور کے مالک کا ہے، کسی ورک اسپیس رول کا نہیں:

  • تعریف ہوسٹ پر چلتی ہے جب اس کی ہوسٹ پلیسمنٹ ہو، کوئی چیک ہو جو کمانڈ چلائے، یا provision یا archive ٹاسک ہو۔ یہ ٹاسکس پلیسمنٹ کچھ بھی ہو، ہوسٹ پر اسپیس کے ورک ٹری میں چلتے ہیں۔
  • صرف سرور کا مالک ایسی تعریف محفوظ یا منظور کر سکتا ہے جو ہوسٹ پر چلتی ہو۔ اس میں ریپو فائل کے نئے ورژن کی منظوری بھی شامل ہے۔ جو ورک اسپیس ایڈمن یہ کوشش کرتا ہے اسے یہ پیغام ملتا ہے: “صرف سرور کا مالک ایسا انوائرنمنٹ محفوظ یا منظور کر سکتا ہے جو سرور ہوسٹ پر چلتا ہے۔ ورک اسپیس ایڈمن وہ انوائرنمنٹ استعمال کر سکتا ہے جو Rig میں چلتا ہو۔”
  • ورک اسپیس ایڈمن ایسی تعریف محفوظ اور منظور کر سکتا ہے جو مکمل طور پر Rig میں چلتی ہو: "placement": "rig"، کوئی چیک کمانڈ نہیں اور کوئی provision یا archive ٹاسک نہیں۔
  • ممبرز دونوں صورتوں میں ماحول شروع، بند اور استعمال کرتے ہیں۔
  • ہوسٹ پر چلنے والی تعریف صرف اُس وقت چلتی ہے جب موجودہ سرور کا مالک اسے محفوظ یا منظور کر چکا ہو۔ سرور یہ منظوری خود ریکارڈ کرتا ہے اور ہر شروع، چیک، ٹاسک اور pull request ہیڈ سنک سے پہلے اسے جانچتا ہے۔ وہ تعریف جسے موجودہ مالک نے منظور نہ کیا ہو، جیسے وہ جسے پچھلے مالک نے محفوظ کیا تھا، ماحولوں کی فہرست اور ایڈیٹر میں اپنی قطار کے نیچے انتظار کرتی ہے۔ سرور کا مالک “یہ سرور پر چلتا ہے۔ شروع ہونے کے لیے اسے منظور کریں۔” دیکھتا ہے، ساتھ منظور کریں، جو اسے بغیر تبدیلی کے محفوظ کرتا ہے؛ باقی سب “یہ سرور پر چلتا ہے۔ شروع ہونے سے پہلے سرور کے مالک کو اسے منظور کرنا ہوگا۔” دیکھتے ہیں۔
  • جو ماحول اس منظوری کا منتظر ہو وہ کہتا ہے “سرور کے مالک نے ابھی تک یہ انوائرنمنٹ منظور نہیں کیا، اس لیے یہ اس سرور پر نہیں چل سکتا۔” سرور کا مالک اس کی جگہ یہ دیکھتا ہے: “آپ نے ابھی تک یہ انوائرنمنٹ منظور نہیں کیا۔ یہ اس سرور پر چلتا ہے، اس لیے آپ کے اس کی تعریف منظور کرنے کے بعد یہ شروع ہوگا۔” ساتھ جائزہ لیں اور منظور کریں، جو تعریف کھولتا ہے۔
  • ماحول کے پروسیس ٹرمینلز، اور وہ ٹرمینل جو شروع ہونا آپ کی ضرورت پر کھولتا ہے، سرور ہوسٹ پر چلتے ہیں۔ کسی میں ٹائپ کرنے، اس کا سائز بدلنے یا اسے بند کرنے کے لیے اس اسپیس کی ہر ریپوزٹری پر لکھنے کی رسائی درکار ہے جو آپ کے اپنے فورج sign-in سے پڑھی جا سکے: ماحول شروع کرنے جیسی ہی شرط۔ باقی کوئی بھی ان ٹرمینلز تک بالکل نہیں پہنچ سکتا۔

سادہ compose ریپو کو بس اتنا چاہیے:

{
"contract": 1,
"name": "Shop",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"components": [ { "kind": "compose", "id": "stack" } ]
}

باقی ہر چیز کا ڈیفالٹ ہے: compose فائل خود مل جاتی ہے، ہر سروس چلتی ہے، پورٹس تفویض ہوتے ہیں، HTTP اینڈ پوائنٹس کا پتہ چلتا ہے اور ماحول کا نام برانچ پر رکھا جاتا ہے۔

ماحول کمپوننٹس کی ترتیب وار فہرست ہے۔ ہر کمپوننٹ پچھلے کے تیار ہونے کا انتظار کرتا ہے، الا یہ کہ after کسی اور کا نام لے، اور روکنا الٹی ترتیب میں ہوتا ہے۔ enabledWhen کمپوننٹ کو کسی آپشن یا رول سے مشروط کرتا ہے، مثلاً opt.seed، !opt.seed یا repo.web۔ وہ کمپوننٹ جس کا رول اختیاری ہو اور اسپیس میں موجود نہ ہو اسی طرح چھوڑ دیا جاتا ہے، اور enabledWhen کی ضرورت نہیں: وہ شروع نہیں ہوتا اور اس کے پاس {port.*} یا {url.*} نہیں ہوتے، اس لیے اسے پڑھنے والا کوئی اور کمپوننٹ شروع ہونے میں ناکام ہو جاتا ہے۔

قسم کون چلاتا ہے استعمال
compose Control Center کا compose ڈرائیور کوئی بھی compose فائل، ہر ماحول میں ایک
cli آپ کا ٹول۔ Control Center میپ شدہ افعال بلاتا ہے اور JSON پڑھتا ہے ایسا ٹول جو اپنا لائف سائیکل، ڈومینز اور ڈیٹا خود سنبھالتا ہے
process Control Center، نگرانی شدہ ٹرمینل سیشن میں ڈیو سرورز اور ورکرز
task Control Center، ہر ٹرگر پر ایک بار انسٹال، مائیگریشنز، ٹیسٹ
app Control Center، جب کوئی ایپ کھولیں پر کلک کرے ڈیسک ٹاپ ایپ

task کمپوننٹس when فہرست لیتے ہیں:

ٹرگر کب چلتا ہے
provision جب worktree بنتا ہے (نیچے worktree ٹاسکس دیکھیں)
create ہر ماحول میں ایک بار، اور ری سیٹ کے بعد دوبارہ
start ہر شروع پر
change سنک کے بعد، جب بدلا ہوا پاتھ onChange سے ملے
manual درخواست پر: چلائیں، cc-env run <id> یا environment_run_task
archive worktree ختم ہونے سے عین پہلے

شروع کے دوران جس ٹاسک کے لیے کچھ کرنا نہ ہو وہ بیکار دکھایا جاتا ہے اور ماحول کے شروع ہوتے وقت دکھائی جانے والی مراحل کی فہرست میں شامل نہیں ہوتا: manual یا change ٹاسک، یا وہ create ٹاسک جو پہلے چل چکا ہو۔

ارے کی صورت میں دی گئی کمانڈ argv ہوتی ہے، اس لیے آپشن کی قدریں کبھی شیل سے نہیں گزرتیں۔ اسٹرنگ، یا لائنوں کی ارے والا script، bash -lc کے تحت چلتا ہے۔ {name}، {branch}، {stateDir}، {repo.<role>}، {port.<key>}، {opt.<key>} اور {url.<role>} جیسے پلیس ہولڈرز صرف argv میں پھیلتے ہیں۔ شیل کمانڈز یہی قدریں CC_ENV_* متغیرات سے پڑھتی ہیں، جیسے $CC_ENV_PORT_WEB۔ شامل کمپوننٹ میں کوئی نامعلوم پلیس ہولڈر ہو تو کچھ بھی چلنے سے پہلے شروع رک جاتا ہے۔

ہر کمانڈ اور اسپیس ٹرمینل کو CC_ENV_NAME، CC_ENV_STATE_DIR، CC_ENV_URL، CC_SPACE_ID، CC_ENV_REPO_<ROLE> بھی ملتے ہیں، اور PR اسپیسز میں CC_PR_NUMBER اور CC_PR_IS_FORK بھی۔ compose کمپوننٹ کے ساتھ COMPOSE_PROJECT_NAME اور COMPOSE_FILE بھی ملتے ہیں، اس لیے ٹاسک میں docker compose exec درست پروجیکٹ تک پہنچتا ہے۔

تعریف رولز کو ورک اسپیس ریپوز سے جوڑتی ہے، تاکہ ایک اسٹیک کئی ریپوز پر پھیل سکے:

"repos": {
"api": { "repoId": "<api>", "anchor": true, "required": true },
"web": { "repoId": "<web>", "anchor": true },
"e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }
}
  • anchor: اسپیس ماحول شروع کر سکتی ہے جب اس میں کم از کم ایک اینکر رول ہو۔ اگر دو تعریفیں ملیں تو شروع کرنے والا چنتا ہے۔
  • required: اس ریپو کے بغیر اسٹیک نہیں چل سکتا۔
  • whenMissing: اسپیس میں رول نہ ہونے پر کیا ہو۔ addToSpace ریپو کو ڈیفالٹ برانچ پر شامل کرتا ہے اور required رولز کا ڈیفالٹ ہے۔ useSource آپ کا رجسٹرڈ چیک آؤٹ دیتا ہے، جسے صرف پڑھنے کے لیے سمجھیں۔ skip متغیر کو خالی چھوڑتا ہے اور باقی صورتوں میں ڈیفالٹ ہے۔
  • شروع کرنے کے لیے اسپیس میں اینکر ریپو پر write اجازت اور باقی ہر جڑے ریپو تک پڑھنے کی رسائی درکار ہے۔

کمانڈ repos میں اعلان کردہ پہلے رول میں چلتی ہے، کسی اور رول میں نہیں جو اسپیس کے پاس اتفاق سے ہو، اس لیے ایک ریپو والی تعریف میں اس کا ذکر نہیں ہوتا۔ کوئی بھی کمپوننٹ "cwd": { "role": "e2e", "path": "packages/ui" } سے اسے بدل سکتا ہے۔ دونوں فیلڈز اختیاری ہیں۔ جب ممکن ہو کہ کسی اسپیس میں پہلا رول موجود نہ ہو، کیونکہ وہ نہ required ہے نہ واحد اینکر، تو ہر کمپوننٹ کو اپنا رول نام لینا ہوگا۔

Control Center کچھ بھی شروع ہونے سے پہلے پورے ہوسٹ کی مشترکہ رینج سے ہوسٹ پورٹس تفویض کرتا ہے (ڈیفالٹ 42000 سے 49999، 32 کے بلاکس میں)۔ پورٹ ماحول کی پوری زندگی میں وہی رہتا ہے، اور compose پورٹس صرف 127.0.0.1 سے جڑتے ہیں۔

  • compose پورٹس کو ڈیکلیئر کرنے کی ضرورت نہیں۔ انہیں {port.postgres.5432} یا CC_ENV_PORT_POSTGRES_5432 کے طور پر پڑھیں۔
  • باقی پورٹس وہیں ڈیکلیئر ہوتے ہیں جہاں استعمال ہوں، "port": "web" یا "ports": ["web", "hmr"] سے، اور {port.web} کے طور پر پڑھے جاتے ہیں۔ پورٹ والے پروسیس کو PORT اور HOST=127.0.0.1 بھی ملتے ہیں۔

HTTP اینڈ پوائنٹس کو سرور کے راؤٹر پر URL ملتا ہے، جو ایک loopback پورٹ پر سنتا ہے:

http://<endpoint>--<name>--<project>.localhost:<router port>
http://web--fix-login--shop.localhost:7355
  • <name> برانچ کا slug ہے، یا PR اسپیس میں pr-<n>۔ <project> naming.project ہے، ورنہ تعریف کا نام۔
  • *.localhost نام loopback کی طرف جاتے ہیں، اس لیے hosts اندراج یا DNS درکار نہیں، اور ہوسٹ نیم ماحولوں کے درمیان کوکیز الگ رکھتا ہے۔
  • HTTP کا جواب دینے والے compose پورٹس کا پتہ چل جاتا ہے، اور کمپوننٹ پر http اس اندازے کی جگہ لیتا ہے۔ پروسیس کو "endpoint": { "role": "web", "primary": true } چاہیے، جس سے {url.web} بھی دستیاب ہوتا ہے۔
  • براؤزر (VM) میں Browser (VM) میں کھولیں استعمال کریں۔ وہاں https://web--fix-login--shop.localhost/ اسی روٹ تک پہنچتا ہے۔
  • پورا لیبل 63 حروف کے اندر رہتا ہے، اس لیے لمبے نام ہیش سے چھوٹے کیے جاتے ہیں۔
  • دو اینڈ پوائنٹس کا مشترکہ پیرنٹ ڈومین نہیں ہوتا۔ جس ایپ کو دونوں پر ایک کوکی چاہیے اسے دونوں ایک اینڈ پوائنٹ سے پیش کرنے ہوں گے۔

جن URLs کو پہلے سے رجسٹر کرنا ہو، جیسے OAuth ری ڈائریکٹس، ان کے لیے "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } ناموں کا مقررہ سیٹ دیتا ہے۔

policy طے کرتی ہے کہ ماحول کب چلیں۔ autoCreate کی قدر off، prSpaces یا allSpaces ہے، idleStopMinutes کا ڈیفالٹ 240 ہے، followPrHead head ہلنے پر PR ماحول کو سنک کرتا ہے، اور maxRunning (ڈیفالٹ 6) کے ساتھ شروع سب سے پرانے استعمال شدہ ماحول کو روکنے کی پیشکش کرتا ہے۔

ایک compose فائل سے ویب ایپ اور Postgres، git سے نظرانداز .env، مائیگریشنز اور ٹیسٹ ٹاسک کے ساتھ۔ seedFiles نامزد فائلیں آپ کے رجسٹرڈ چیک آؤٹ سے ہر نئے worktree میں کاپی کرتا ہے۔

{
"contract": 1,
"name": "Shop",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"naming": { "project": "shop" },
"seedFiles": [".env"],
"components": [
{ "kind": "compose", "id": "stack",
"services": ["postgres", "web"],
"healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } },
{ "kind": "task", "id": "migrate", "when": ["create", "change"],
"onChange": ["db/migrations/**"],
"command": "docker compose exec -T web bin/migrate" },
{ "kind": "task", "id": "test", "when": ["manual"],
"command": "docker compose exec -T web bin/test" }
]
}

healthchecks اس سروس کو بھی اگلے کمپوننٹ کو روکنے دیتا ہے جس کی اپنی ہیلتھ چیک نہ ہو۔ اس کے بغیر چلتا کنٹینر تیار مانا جاتا ہے، اور مائیگریشنز ابھی شروع ہوتے ڈیٹا بیس سے آگے نکل سکتی ہیں۔

ہر شروع اور ریفریش up کو --remove-orphans کے ساتھ چلاتا ہے، اس لیے جو سروس compose فائل سے ہٹا دی گئی ہو وہ رک جاتی ہے اور اپنا پورٹ خالی کر دیتی ہے۔ امیجز شروع پر اور ریفریش پر بنتی ہیں، جب تک کمپوننٹ "build": false مقرر نہ کرے۔

ایک فرضی ٹول acme جو اپنے کنٹینرز، ڈومینز اور TLS خود سنبھالتا ہے۔ Control Center {name} دیتا ہے اور باقی سب status سے جانتا ہے۔ یہ کبھی ٹول کے ہوسٹ نیم اخذ نہیں کرتا اور کبھی /etc/hosts میں ترمیم نہیں کرتا۔

{
"contract": 1,
"name": "Acme",
"repos": {
"server": { "repoId": "<server>", "anchor": true, "required": true },
"web": { "repoId": "<web>", "anchor": true }
},
"routing": { "mode": "tool", "domain": "acme.test", "upstream": "127.0.0.1:443",
"tls": true, "caFile": "~/.acme/tls/ca.crt" },
"components": [
{ "kind": "cli", "id": "acme",
"verbs": {
"create": ["acme", "env", "create", "{name}",
{ "if": "!interactive", "args": ["--json"] },
{ "if": "repo.web", "args": ["--web-dir", "{repo.web}"] }],
"start": ["acme", "env", "start", "{name}"],
"stop": ["acme", "env", "stop", "{name}"],
"destroy": ["acme", "env", "destroy", "{name}", "--yes"],
"reset": ["acme", "env", "reset-db", "{name}"],
"status": ["acme", "env", "status", "{name}", "--json"],
"list": ["acme", "env", "ls", "--json"],
"logs": ["acme", "env", "logs", "{name}",
{ "if": "service", "args": ["{service}"] },
"--tail", "{tail}",
{ "if": "follow", "args": ["--follow"] }],
"exec": ["acme", "env", "exec", "{name}", "{service}", "{command}"]
},
"interactive": ["create"],
"keepsDataOnStop": false,
"statusMap": {
"state": [
{ "when": { "path": "/status/ready", "equals": true }, "state": "ready" },
{ "when": { "none": "/status/containers", "where": { "state": "running" } },
"state": "stopped" },
{ "when": { "path": "/status/phase", "equals": "failed" }, "state": "failed" },
{ "state": "starting" }
],
"detail": "phase: {/status/phase}",
"warnings": [
{ "when": { "path": "/status/dnsWorking", "equals": false },
"message": "Not resolvable on this host" }
],
"endpoints": [
{ "role": "app", "label": "App", "url": "/urls/app", "primary": true },
{ "role": "db", "hostPort": "/ports/db" }
],
"services": "/status/containers/*/service",
"list": "/*/slug",
"missingErrorCodes": ["env.not-found"]
} }
]
}
  • create، status اور destroy لازمی ہیں۔ Control Center پڑھی گئی حالت سے create یا start چنتا ہے۔ کوئی بھی فعل argv کے بجائے { "shell": "…" } ہو سکتا ہے۔
  • interactive ان افعال کے نام بتاتا ہے، جو create، start اور reset میں سے ہیں، اور جو ٹرمینل پر اپنی ضرورت کی چیز مانگ سکتے ہیں۔ جب ایسا فعل اس شخص کے لیے 3 کے کوڈ کے ساتھ ختم ہو جو شروع دبائے، Control Center وہی فعل ٹرمینل ٹیب میں دوبارہ چلاتا ہے، اور شروع کارروائی اس کے 0 کوڈ کے ساتھ ختم ہونے پر جاری رہتی ہے۔ وہاں شرط interactive درست ہوتی ہے اور CC_ENV_INTERACTIVE=1 سیٹ ہوتا ہے، اس لیے { "if": "!interactive", "args": ["--json"] } پائپ کے لیے مشین آؤٹ پٹ برقرار رکھتا ہے۔ ایجنٹ کی شروعات یا خودکار شروعات کبھی ٹرمینل نہیں کھولتی: ماحول کارروائی درکار ہے دکھاتا ہے اور انتظار کرتا ہے۔
  • اگر destroy ناکام ہو تب بھی ماحول ہٹا دیا جاتا ہے جب status بعد میں missing رپورٹ کرے، اس طرح وہ ماحول جو ٹول اب نہیں رکھتا ہمیشہ ہٹایا جا سکتا ہے۔
  • list Control Center کو اس ماحول کا پتا لگانے دیتا ہے جو ٹول کھو چکا ہو۔ ماحول کو گمشدہ تبھی نشان زد کیا جاتا ہے جب اس کا نام list میں نہ ہو اور اس کے بعد status missing کہے۔ جو آؤٹ پٹ فہرست کے طور پر نہ پڑھا جا سکے وہ کچھ نہیں بدلتا۔
  • logs اور exec میں {service} ایک ہی لفظ ہونا چاہیے جو - سے شروع نہ ہو، اور ان سروسز میں سے ایک ہو جو ٹول نے آخری بار رپورٹ کی تھیں، جب اس نے کوئی رپورٹ کی ہو۔
  • statusMap ٹول کا اپنا JSON، JSON پوائنٹرز سے پڑھتا ہے، جہاں * ہر آئٹم سے ملتا ہے۔ حالت کے اصول ترتیب وار ہیں اور پہلا میل جیتتا ہے۔ شرط path کے ساتھ equals ہے، یا any یا none کے ساتھ where۔
  • keepsDataOnStop: false آئیڈل اسٹاپ بند کرتا ہے اور روکیں میں ڈیٹا ضائع ہونے کی وارننگ شامل کرتا ہے۔ اسے تب سیٹ کریں جب روکنے سے ڈیٹا ضائع ہو۔
  • routing.mode: "tool" ٹول کے ہوسٹ نیمز کو براؤزر (VM) اور ایجنٹس سے جوڑتا ہے۔ ڈومین کا اختتام .test، .localhost یا .internal پر ہونا چاہیے، اور اس سے باہر رپورٹ شدہ URL چھوڑ دیا جاتا ہے۔

آپ کا اپنا ٹول statusMap چھوڑ کر اس صفحے کے آخر میں بیان کردہ اسٹیٹس کنٹریکٹ پرنٹ کر سکتا ہے۔

صرف پروسیسز اور ٹاسکس، کوئی کنٹینر نہیں۔ ویب ایپ {url.api} کے ذریعے API ڈھونڈتی ہے۔

{
"contract": 1,
"name": "Monorepo",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"naming": { "project": "mono" },
"options": [ { "key": "seed", "type": "bool", "default": true, "agentDefault": false } ],
"components": [
{ "kind": "task", "id": "install", "when": ["provision", "change"],
"onChange": ["pnpm-lock.yaml"],
"command": ["pnpm", "install", "--frozen-lockfile"] },
{ "kind": "process", "id": "api", "label": "API", "port": "api",
"cwd": { "path": "apps/api" },
"command": ["pnpm", "dev"],
"endpoint": { "role": "api" },
"ready": { "http": "http://127.0.0.1:{port.api}/health", "timeout": 120 },
"restartOn": ["pnpm-lock.yaml"] },
{ "kind": "task", "id": "seed", "when": ["create"], "enabledWhen": "opt.seed",
"cwd": { "path": "apps/api" },
"command": ["pnpm", "db:seed"] },
{ "kind": "process", "id": "web", "label": "Dev server", "port": "web",
"cwd": { "path": "apps/web" },
"env": { "API_URL": "{url.api}" },
"command": ["pnpm", "dev", "--port", "{port.web}", "--host", "127.0.0.1"],
"endpoint": { "role": "web", "primary": true },
"ready": { "http": "http://127.0.0.1:{port.web}/" } },
{ "kind": "task", "id": "lint", "when": ["manual"], "command": ["pnpm", "lint"] }
]
}
  • ہر پروسیس ایک ٹرمینل ٹیب ہے جسے آپ کھول، پڑھ اور اس میں ٹائپ کر سکتے ہیں، اگر آپ کے پاس اسپیس کی ہر ریپوزٹری پر لکھنے کی رسائی ہو (دیکھیں کون کیا محفوظ کر سکتا ہے)۔ ٹیب بند کرنے سے وہ نہیں رکتا۔
  • ready http (مکمل URL)، tcp (host:port) یا logMatch (باقاعدہ اظہار) لیتا ہے۔ restart کی قدر on-failure (ڈیفالٹ)، always یا never ہے۔ restartOn بدلا ہوا پاتھ ملنے پر پروسیس دوبارہ شروع کرتا ہے۔
  • options شروع پر فارم بن جاتے ہیں، اور agentDefault ایجنٹ کی شروع کردہ رنز پر لاگو ہوتا ہے۔

بلڈ مرحلے والی ڈیسک ٹاپ ایپ۔ ایپ کسی بھی ٹیکنالوجی سے بنی ہو ایک ہی طرح کام کرتی ہے، کیونکہ Control Center آپریٹنگ سسٹم کی ونڈو سطح پر کام کرتا ہے اور ایپ میں کوئی ہک یا SDK نہیں چاہیے۔

{
"contract": 1,
"name": "Studio",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"components": [
{ "kind": "task", "id": "build", "when": ["manual"], "command": ["pnpm", "build"] },
{ "kind": "app", "id": "desktop", "label": "Studio", "prepare": "build",
"command": ["dist/mac-arm64/Studio.app/Contents/MacOS/Studio"],
"isolate": "home" }
]
}

ایپ ماحول کے ساتھ شروع نہیں ہوتی۔ کوئی ایپ کھولیں پر کلک کرتا ہے اور پہلے prepare چلتا ہے۔ دوبارہ بنائیں اور کھولیں یہ جوڑا دوبارہ چلاتا ہے۔ enabledWhen ایپ اور اس کے prepare ٹاسک دونوں پر لاگو ہوتا ہے، اور جب دونوں میں سے کوئی بھی بند ہو تو ایپ کھولیں مسترد ہو جاتا ہے۔ ایپ اس وقت چلتی سمجھی جاتی ہے جب اس کے پروسیس گروپ کا کوئی بھی پروسیس چل رہا ہو، اس لیے وہ لانچر ٹھیک ہے جو ایپ شروع کرے اور خود ختم ہو جائے۔ اگر ایپ کھولیں کے تقریباً 5 سیکنڈ کے اندر سب کچھ ختم ہو جائے تو ایپ آخری لاگ لائنوں کے ساتھ ناکام دکھائی دیتی ہے۔ اس کے بعد صاف اخراج بند کے طور پر دکھتا ہے اور کریش آخری لاگ لائنیں دکھاتا ہے، اور ان میں سے کوئی بھی اسے دوبارہ شروع نہیں کرتا۔ سرور کی دوبارہ شروعات ایپ کو بند کرتی ہے اور اسے کبھی دوبارہ نہیں کھولتی، اور آئیڈل اسٹاپ چلتی ایپ کو نہیں چھیڑتا۔

  • macOS پر سسٹم سیٹنگز میں Control Center کو ایک بار Screen Recording اور Accessibility کی اجازت دیں۔ سرور ہوسٹ کو GUI سیشن چاہیے: headless سرور ایپ چلانے سے انکار کرتا ہے۔
  • بائنری کو براہ راست چلائیں۔ open -a ایپ کو LaunchServices کے حوالے کرتا ہے اور وہ اس پروسیس ٹری سے نکل جاتی ہے جسے Control Center ٹریک کرتا ہے، اس لیے ایپ شروع ہوتے ہی ناکام دکھائی دیتی ہے۔
  • ونڈوز ڈسپلے پر رہتی ہیں۔ macOS تمام ڈسپلے سے باہر رکھی ونڈو کیپچر نہیں کرتا، اس لیے ایجنٹ کے زیر استعمال ایپ سرور کی اسکرین پر نظر آتی ہے۔ اسے فوکس درکار نہیں۔
  • "isolate": "home" ایپ کو HOME، XDG_* اور CFFIXED_USER_HOME کے ذریعے نجی ہوم دیتا ہے، تاکہ دو اسپیسز کی کاپیاں ساتھ ساتھ چل سکیں۔ NSUserDefaults الگ نہیں ہوتا، اس لیے Cocoa ترجیحات اور Flutter کا shared_preferences کاپیوں میں مشترک رہتے ہیں۔
  • isolate صرف شروع کیے گئے پروسیس پر لاگو ہوتا ہے۔ flutter run جیسے ٹول چین لانچر کو اصل ہوم چاہیے، اس لیے isolate کو بنی ہوئی بائنری کے ساتھ استعمال کریں۔ اگر ایپ کی اپنی سیٹنگ ہو، جیسے --user-data-dir، تو اسے ترجیح دیں۔
  • ایجنٹس app_use سے ونڈو چلاتے ہیں، جو صرف اس ماحول کے پروسیس ٹری تک پہنچتا ہے۔ ایجنٹ ونڈو دیکھتا ہے، ڈیسک ٹاپ نہیں۔ ایجنٹ کی لانچ ایکشن پالیسی سے گزرتی ہے اور ڈیفالٹ طور پر پوچھتی ہے، اور جب کسی انسان کے پاس کنٹرول ہو تو ایجنٹ کا ان پٹ رک جاتا ہے۔
  • "input": "background" (ڈیفالٹ) ایونٹس پروسیس کو بھیجتا ہے۔ "foreground" ونڈو فعال کرتا ہے اور کرسر سنبھال لیتا ہے۔

provision اور archive ٹاسکس ریپو کا سیٹ اپ اور ٹیئر ڈاؤن اس کے worktree کے ساتھ چلاتے ہیں۔ ترتیبات → ورک اسپیس → ریپوزٹریز میں ریپو کی قطار کا آئیکن ریپو کی تعریف کھولتا ہے۔

یہ ٹاسکس ماحول نہیں بلکہ worktree کے ساتھ چلتے ہیں، اس لیے ان اسپیسز میں بھی چلتے ہیں جہاں کوئی شروع نہیں دباتا:

provision archive
چلتا ہے جب رول کا worktree بنے، کسی بھی اسپیس میں اس worktree کے ختم ہونے سے عین پہلے
ناکامی پر پروویژننگ ناکام ہوتی ہے اور worktree ختم ہوتا ہے درج ہوتا ہے، حذف کرنے کو کبھی نہیں روکتا
ڈیفالٹ ٹائم آؤٹ 5 منٹ 2 منٹ
دیکھتا ہے CC_WORKSPACE_PATH، CC_ROOT_PATH، CC_SPACE_*، CC_REPO_NAME وہی

بغیر اسٹیک والے ریپو کو صرف ایسی تعریف چاہیے جس میں اس کے ٹاسکس ہوں۔ شروع کرنے کو کچھ نہ ہونے کی وجہ سے اینکر رول درکار نہیں:

{
"contract": 1,
"name": "Web",
"repos": { "app": { "repoId": "<id>" } },
"components": [
{ "kind": "task", "id": "setup", "when": ["provision"],
"script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] }
]
}
  • ابھی کوئی ماحول نہیں، اس لیے یہ ٹاسکس {name}، {port.*}، {url.*}، {opt.*} یا enabledWhen استعمال نہیں کر سکتے، اور انہیں تعریف کا env نہیں ملتا۔
  • کسی ریپو کے provision اور archive ٹاسکس صرف ایک تعریف رکھ سکتی ہے۔ دوسری تعریفیں باقی کاموں کے لیے اسے جوڑ سکتی ہیں۔
  • "when": ["provision", "change"] لاک فائل بدلنے پر بھی دوبارہ انسٹال کرتا ہے۔
  • ٹاسک اپنے cwd رول کے worktree کے لیے چلتا ہے، اس لیے کئی ریپوز والی تعریف ہر ریپو کو الگ سیٹ اپ کر سکتی ہے۔
  • ٹیسٹ رن CC_SCRIPT_TEST=1 سیٹ کرتا ہے۔ دوبارہ کوشش صاف worktree سے شروع ہوتی ہے، اس لیے ایسے ٹاسکس لکھیں جو دوبارہ چلنا برداشت کر سکیں۔

ایجنٹس کو کبھی Docker ساکٹ نہیں ملتا۔ اہل تعریف والی اسپیس میں رن کو اپنے PATH پر cc-env ملتا ہے۔ اسپیس رن سے آتی ہے، اس لیے ایجنٹ صرف اپنے ماحول پر عمل کر سکتا ہے، اور ہر کمانڈ ایکشن پالیسی سے گزرتی ہے۔

ٹرمنل ونڈو
cc-env status
cc-env up
cc-env down
cc-env reset
cc-env destroy
cc-env restart <process>
cc-env logs <name>
cc-env exec <service> -- <cmd>
cc-env run <task> -- <args>

compose کمپوننٹ کے ساتھ docker شم ps، logs، exec، port، restart اور top کے ساتھ docker compose کی بھی اجازت دیتا ہے، اور صرف اسی ماحول کے اپنے compose پروجیکٹ کے خلاف۔ فعل سے پہلے کوئی فلیگ نہیں آ سکتا، اور ہر فعل کے کچھ مخصوص آپشنز ہیں: logs فالو نہیں کر سکتا اور exec صرف -T (یا --no-tty) لیتا ہے۔ وہ آپشنز جو compose کو کسی اور فائل یا پروجیکٹ کی طرف لے جائیں (-f، -p، --project-directory، --env-file، --profile) کہیں بھی ہوں، مسترد ہوتے ہیں۔ باقی سب کوڈ 5 اور “not available in Control Center agent runs” کے ساتھ ختم ہوتا ہے۔

جس ریپو کی اسکلز اس کا اپنا ٹول بلاتی ہیں وہ ایسا کرتا رہ سکتا ہے۔ cli کمپوننٹ پر agentPassthrough بلاک بتاتا ہے کہ ایجنٹس کون سی کمانڈز چلا سکتے ہیں۔ صرف وہ کمانڈز گزرتی ہیں جو منظور شدہ تعریف میں درج ہوں، اور ہر ایک ہوسٹ پر چلتی ہے، اس لیے اس پر میزبان پر کمانڈز چلائیں کا اصول لاگو ہوتا ہے، جو ڈیفالٹ میں پہلے پوچھتا ہے:

"agentPassthrough": {
"binary": "acme",
"allow": [
{ "argv": ["env", "ls"], "maps": "status", "nameFilter": true },
{ "argv": ["env", "status|url"], "maps": "status", "positionalName": 2 },
{ "argv": ["env", "create"], "maps": "up", "positionalName": 2,
"pathFlags": ["--web-dir"], "denyFlags": ["--force"] },
{ "argv": ["env", "logs"], "maps": "logs", "positionalName": 2,
"denyFlags": ["--follow"] }
]
}

maps اس آپریشن کا نام ہے جس کی پالیسی لاگو ہوتی ہے۔ positionalName اس آرگیومنٹ کو اس اسپیس کے ماحول پر مجبور کرتا ہے، nameFilter JSON آؤٹ پٹ کو اسی تک فلٹر کرتا ہے، اور ہر pathFlags قدر رن کے worktrees کے اندر ہونی چاہیے۔ جو کمانڈ کسی اصول سے نہ ملے وہ کوڈ 5 پر ختم ہوتی ہے۔

یہی آپریشن ٹولز کے طور پر بھی ہیں: environment_status، environment_up، environment_down، environment_reset، environment_destroy، environment_restart، environment_exec، environment_logs، environment_run_task، environment_launch_app اور environment_stop_app۔ سینڈ باکس میں ایجنٹس اپنے پورٹس تک براہ راست اور ماحول کے ہوسٹ نیمز تک رن کی پراکسی سے پہنچتے ہیں، اس لیے انہیں کہیں کہ URL کا اندازہ لگانے کے بجائے environment_status سے اینڈ پوائنٹس پڑھیں۔

فورک PR کا کوڈ قابل اعتماد نہیں، اور ہوسٹ پلیسمنٹ میں یہ سرور کے OS صارف کے طور پر چلتا ہے۔ policy.forkPrs طے کرتا ہے کہ کیا ہو:

قدر اثر ڈیفالٹ برائے
rig compose فائل بغیر پوچھے VM میں چلتی ہے صرف compose اور task کمپوننٹس والی تعریفیں
approval ہر شروع پر ایڈمن درکار ہے باقی تمام تعریفیں
deny مسترد کوئی نہیں
  • seedFiles فورک کے لیے کبھی کاپی نہیں ہوتیں، کیونکہ عموماً راز ہوتی ہیں۔ ان میں سے کسی کو جوڑنے والی compose فائل گمشدہ فائل کا نام بتاتی ہے۔
  • provision اور archive ٹاسکس چھوڑ دیے جاتے ہیں، الا یہ کہ پالیسی rig ہو، تب وہ VM میں چلتے ہیں۔
  • ہوسٹ پلیسمنٹ میں فورک پر privileged، ہوسٹ نیم اسپیسز، Docker ساکٹ بائنڈ، devices اور اسپیس کے worktrees سے باہر بائنڈز مسترد ہوتے ہیں۔ قابل اعتماد اسپیسز میں یہ صرف وارننگ دیتے ہیں۔

"placement": "rig" compose اور task کمپوننٹس کو مخصوص microVM میں چلاتا ہے۔ process، cli یا app کمپوننٹس والی تعریفیں اہل نہیں۔ compose فائل بغیر تبدیلی چلتی ہے، بغیر ہوسٹ Docker ساکٹ اور آپریٹر کی اسناد کے، اور نیٹ ورک رسائی صرف ان رجسٹریز تک ہوتی ہے جو اس کی امیجز کو چاہییں۔ worktree لائیو ماؤنٹ ہوتا ہے۔

  • arm64 گیسٹس۔ Apple Silicon پر گیسٹس arm64 ہیں، اس لیے صرف amd64 امیجز نہیں چلیں گی۔
  • نجی رجسٹریز مسترد ہوتی ہیں۔ گیسٹس کے پاس رجسٹری اسناد نہیں، اس لیے معلوم عوامی رجسٹریز سے باہر کی امیج VM بوٹ ہونے سے پہلے مسترد ہو جاتی ہے۔ عوامی رجسٹری پر نجی ریپوزٹری تب ناکام ہوتی ہے جب گیسٹ اسے کھینچتا ہے۔
  • 16 GiB اسٹوریج۔ اسٹیک کی تمام امیجز اور والیومز ایک 16 GiB ڈسک بانٹتے ہیں، اور اسے بڑھایا نہیں جا سکتا۔
  • پہلا بوٹ سست ہے۔ امیج لیئرز ہر VM کی الگ ہوتی ہیں، اس لیے پہلا بوٹ سب کچھ کھینچتا ہے۔ رکی ہوئی رگ اپنی ڈسک رکھتی ہے۔
  • بیس امیجز پڑھنے کے قابل ہوں۔ جو Dockerfile بیس امیج کا نام متغیر سے دے اس کی منصوبہ بندی نہیں ہو سکتی، کیونکہ نیٹ ورک رسائی بوٹ پر طے ہو جاتی ہے۔
  • مدت۔ policy.rigTtlHours VM ختم کرتا ہے، ڈیفالٹ طور پر 24 گھنٹے بعد۔

statusMap کے بغیر cli کمپوننٹ مقامی کنٹریکٹ cc-env/1 کی توقع کرتا ہے۔ فعل status یہ آبجیکٹ stdout پر پرنٹ کرتا ہے:

{
"state": "ready",
"detail": "migrations applied, HTTP 200",
"endpoints": [
{ "role": "app", "label": "App", "url": "https://fix-login.acme.test", "primary": true },
{ "role": "postgres", "label": "Postgres", "hostPort": 49213 }
],
"services": ["server", "postgres"],
"needsRecreate": false,
"error": { "code": "post-start-failed", "message": "…", "hint": "…", "command": "…" }
}
  • state کی قدر ready، starting، stopped، failed یا missing ہے۔ missing سے create ہوتا ہے، stopped اور failed سے start۔ missing کو ایگزٹ کوڈ 0 کے ساتھ رپورٹ کریں: ناکام status کو failed گنا جاتا ہے۔
  • صرف state ضروری ہے۔ نامعلوم فیلڈز نظرانداز ہوتی ہیں، اور ناقابل تجزیہ آؤٹ پٹ خام متن کی تفصیل کے ساتھ خراب حالت میں دکھتا ہے۔
  • URL کو loopback، *.localhost یا routing.domain کے تحت ہونا چاہیے، ورنہ چھوڑ دیا جاتا ہے۔
  • needsRecreate: true دوبارہ بنائیں دکھاتا ہے، جو ڈیٹا ضائع کرتا ہے۔ Control Center اس پر خود کبھی عمل نہیں کرتا۔
  • فعل list ناموں کی JSON ارے پرنٹ کرتا ہے، یا name والے آبجیکٹس کی۔

ایگزٹ کوڈز ہر فعل پر لاگو ہوتے ہیں:

کوڈ مطلب
0 ٹھیک
3 ٹرمینل پر جواب درکار ہے، جیسے sudo کا پاس ورڈ۔ interactive میں درج فعل شروع دبانے والے شخص کے لیے ٹرمینل ٹیب میں دوبارہ چلتا ہے۔ ورنہ ٹرمینل میں چلائیں ایک اسپیس ٹرمینل کھولتا ہے جس میں ٹول کی command ٹائپ ہوتی ہے مگر چلتی نہیں، پھر دوبارہ کوشش دوبارہ کوشش کرتا ہے۔ Control Center کبھی sudo نہیں چلاتا اور کبھی کسی پرامپٹ کا جواب نہیں دیتا
4 سائن ان درکار ہے۔ ٹول کی command بتاتی ہے کہ کیسے
5 جس چیز پر یہ انحصار کرتا ہے وہ دستیاب نہیں، جیسے کوئی کنٹینر رن ٹائم جو نہیں چل رہا
دیگر ناکامی

کوڈ 3، 4 اور 5 ناکامیاں نہیں ہیں۔ ماحول کارروائی درکار ہے دکھاتا ہے اور انتظار کرتا ہے، اور اگلی شروعات وہیں سے جاری رہتی ہے جہاں وہ رکی تھی۔ جو ٹاسک ان میں سے کسی کے ساتھ ختم ہو اس کا مطلب بھی یہی ہے۔

پیش رفت stderr پر لائن سے الگ JSON کے طور پر جاتی ہے:

{"type":"step","id":"images","label":"Pull images","state":"running"}
{"type":"log","stream":"stdout","line":"postgres Pulled"}
{"type":"step","id":"images","label":"Pulled 4 images","state":"done"}
{"type":"note","level":"warn","message":"Hosts entries stayed behind after destroy"}
{"type":"error","code":"hosts-missing","message":"Add the hosts entry","hint":"Needs sudo","command":"sudo acme hosts add fix-login"}

ماحول شروع ہونے کے دوران پینل ان اجزا کی فہرست دکھاتا ہے جن سے شروع کا عمل گزرتا ہے، ہر ایک کے ساتھ اسپنر، نشان یا کراس۔ step لائن بتاتی ہے کہ ٹول ابھی کیا کر رہا ہے، اور اس کا label ٹول کی اپنی قطار کے نیچے دکھایا جاتا ہے؛ مراحل کبھی نئی قطاریں نہیں بناتے۔ کسی مرحلے کا state pending، running، done یا failed ہوتا ہے، اور جس مرحلے میں state نہ ہو وہ چل رہا ہوتا ہے۔ جو مرحلہ اسی id کے ساتھ دوبارہ رپورٹ کرے (سٹرنگ یا نمبر، یا اسی label کے ساتھ اگر ID نہ ہو) وہ پہلے کی بات کی جگہ لیتا ہے، اس لیے ایک اسپنر والا ٹول ایک id رکھ کر صرف label بدل سکتا ہے۔ IDs کے بغیر مراحل ایک کے بعد ایک آتے ہیں: نیا مرحلہ پچھلے کو ختم کر دیتا ہے۔ جب کمانڈ ختم ہو، تو جو مرحلہ ابھی تک چل رہا ہو وہ اسی طرح ختم ہوتا ہے جیسے کمانڈ ختم ہوئی۔

log لائن ٹول کی JSON میں لپٹی ہوئی آؤٹ پٹ کی ایک سطر لیے ہوتی ہے، اور اسے سادہ آؤٹ پٹ کے طور پر پڑھا جاتا ہے۔ note رن کے آؤٹ پٹ میں جاتا ہے، اور جس کے ساتھ "level": "warn" ہو وہ ماحول پر وارننگ کے طور پر بھی رہتا ہے۔ error قسم کی آخری لائن منظم خرابی بن جاتی ہے، اور command کاپی کے لیے پیش ہوتا ہے، اور آؤٹ پٹ کی آخری 12 لائنیں اس کے message کے نیچے دکھائی جاتی ہیں۔ اس کے بغیر Control Center آخری 20 stderr لائنیں دکھاتا ہے۔ جو JSON نہ ہو وہ عام لاگ آؤٹ پٹ ہے۔